/**
* Copyright 2005-2014 Restlet
*
* The contents of this file are subject to the terms of one of the following
* open source licenses: Apache 2.0 or or EPL 1.0 (the "Licenses"). You can
* select the license that you prefer but you may not use this file except in
* compliance with one of these Licenses.
*
* You can obtain a copy of the Apache 2.0 license at
* http://www.opensource.org/licenses/apache-2.0
*
* You can obtain a copy of the EPL 1.0 license at
* http://www.opensource.org/licenses/eclipse-1.0
*
* See the Licenses for the specific language governing permissions and
* limitations under the Licenses.
*
* Alternatively, you can obtain a royalty free commercial license with less
* limitations, transferable or non-transferable, directly at
* http://restlet.com/products/restlet-framework
*
* Restlet is a registered trademark of Restlet S.A.S.
*/
package org.restlet.ext.html.internal;
import java.io.IOException;
import java.util.Iterator;
import java.util.Map;
import java.util.logging.Level;
import org.restlet.Context;
import org.restlet.data.CharacterSet;
import org.restlet.data.MediaType;
import org.restlet.data.Reference;
import org.restlet.ext.html.FormData;
import org.restlet.representation.Representation;
import org.restlet.util.NamedValue;
import org.restlet.util.Series;
/**
* Representation of a Web form containing submitted entries.
*
* @author Jerome Louvel
*/
public class FormUtils {
/**
* Creates a form data.
*
* @param name
* The name buffer.
* @param value
* The value buffer (can be null).
* @param decode
* If true, the name and values are decoded with the given
* {@link CharacterSet}, if false, than nothing is decoded.
* @param characterSet
* The supported character encoding.
* @return The created form data.
*/
public static FormData create(CharSequence name, CharSequence value,
boolean decode, CharacterSet characterSet) {
FormData result = null;
if (name != null) {
String nameStr;
if (decode) {
nameStr = Reference.decode(name.toString(), characterSet);
} else {
nameStr = name.toString();
}
if (value != null) {
String valueStr;
if (decode) {
valueStr = Reference.decode(value.toString(), characterSet);
} else {
valueStr = value.toString();
}
result = new FormData(nameStr, valueStr);
} else {
result = new FormData(nameStr, (String) null);
}
}
return result;
}
/**
* Reads the entries whose name is a key in the given map.<br>
* If a matching entry is found, its value is put in the map.<br>
* If multiple values are found, a list is created and set in the map.
*
* @param post
* The web form representation.
* @param entries
* The entries map controlling the reading.
* @throws IOException
* If the entries could not be read.
*/
public static void getEntries(Representation post,
Map<String, Object> entries) throws IOException {
if (!post.isAvailable()) {
throw new IllegalStateException(
"The Web form cannot be parsed as no fresh content is available. If this entity has been already read once, caching of the entity is required");
}
new FormReader(post).readEntries(entries);
}
/**
* Reads the entries whose name is a key in the given map.<br>
* If a matching entry is found, its value is put in the map.<br>
* If multiple values are found, a list is created and set in the map.
*
* @param queryString
* The query string.
* @param entries
* The entries map controlling the reading.
* @param characterSet
* The supported character encoding.
* @param separator
* The separator character to append between entries.
* @throws IOException
* If the entries could not be read.
*/
public static void getEntries(String queryString,
Map<String, Object> entries, CharacterSet characterSet,
char separator) throws IOException {
new FormReader(queryString, characterSet, separator)
.readEntries(entries);
}
/**
* Reads the entries with the given name.<br>
* If multiple values are found, a list is returned created.
*
* @param form
* The web form representation.
* @param name
* The name to match.
* @return The form data or list of values.
* @throws IOException
* If the entries could not be read.
*/
public static Object getEntry(Representation form, String name)
throws IOException {
if (!form.isAvailable()) {
throw new IllegalStateException(
"The HTML form cannot be parsed as no fresh content is available. If this entity has been already read once, caching of the entity is required");
}
return new FormReader(form).readEntry(name);
}
/**
* Reads the entries with the given name.<br>
* If multiple values are found, a list is returned created.
*
* @param query
* The query string.
* @param name
* The entry name to match.
* @param characterSet
* The supported character encoding.
* @param separator
* The separator character to append between entries.
* @return The entry value or list of values.
* @throws IOException
* If the entries could not be read.
*/
public static Object getEntry(String query, String name,
CharacterSet characterSet, char separator) throws IOException {
return new FormReader(query, characterSet, separator).readEntry(name);
}
/**
* Reads the first entry with the given name.
*
* @param post
* The web form representation.
* @param name
* The name to match.
* @return The form data entry.
* @throws IOException
*/
public static FormData getFirstEntry(Representation post, String name)
throws IOException {
if (!post.isAvailable()) {
throw new IllegalStateException(
"The Web form cannot be parsed as no fresh content is available. If this entity has been already read once, caching of the entity is required");
}
return new FormReader(post).readFirstEntry(name);
}
/**
* Reads the first entry with the given name.
*
* @param query
* The query string.
* @param name
* The name to match.
* @param characterSet
* The supported character encoding.
* @param separator
* The separator character to append between entries.
* @return The form data entry.
* @throws IOException
*/
public static FormData getFirstEntry(String query, String name,
CharacterSet characterSet, char separator) throws IOException {
return new FormReader(query, characterSet, separator)
.readFirstEntry(name);
}
/**
* Indicates if the searched entry is specified in the given media range.
*
* @param searchedEntry
* The searched entry.
* @param mediaRange
* The media range to inspect.
* @return True if the searched entry is specified in the given media range.
*/
public static boolean isEntryFound(FormData searchedEntry,
MediaType mediaRange) {
boolean result = false;
for (Iterator<? extends NamedValue<String>> iter = mediaRange
.getParameters().iterator(); !result && iter.hasNext();) {
result = searchedEntry.equals(iter.next());
}
return result;
}
/**
* Parses a post into a given entries series.
*
* @param entries
* The target entries series.
* @param post
* The posted form.
*/
public static void parse(Series<FormData> entries, Representation post) {
if (post != null) {
if (post.isAvailable()) {
FormReader fr = null;
try {
fr = new FormReader(post);
} catch (IOException ioe) {
Context.getCurrentLogger().log(Level.WARNING,
"Unable to create a form reader. Parsing aborted.",
ioe);
}
if (fr != null) {
fr.addEntries(entries);
}
} else {
throw new IllegalStateException(
"The Web form cannot be parsed as no fresh content is available. If this entity has been already read once, caching of the entity is required");
}
}
}
/**
* Parses a entries string into a given form.
*
* @param entriesSeries
* The target entries series.
* @param queryString
* The query string.
* @param characterSet
* The supported character encoding.
* @param decode
* Indicates if the query string should be decoded using the
* given character set.
* @param separator
* The separator character to append between entries.
*/
public static void parse(Series<FormData> entriesSeries,
String queryString, CharacterSet characterSet, boolean decode,
char separator) {
if ((queryString != null) && !queryString.equals("")) {
FormReader fr = null;
if (decode) {
fr = new FormReader(queryString, characterSet, separator);
} else {
fr = new FormReader(queryString, separator);
}
fr.addEntries(entriesSeries);
}
}
/**
* Private constructor to ensure that the class acts as a true utility class
* i.e. it isn't instantiable and extensible.
*/
private FormUtils() {
}
}