001: /*
002: * Copyright 2005-2007 Noelios Consulting.
003: *
004: * The contents of this file are subject to the terms of the Common Development
005: * and Distribution License (the "License"). You may not use this file except in
006: * compliance with the License.
007: *
008: * You can obtain a copy of the license at
009: * http://www.opensource.org/licenses/cddl1.txt See the License for the specific
010: * language governing permissions and limitations under the License.
011: *
012: * When distributing Covered Code, include this CDDL HEADER in each file and
013: * include the License file at http://www.opensource.org/licenses/cddl1.txt If
014: * applicable, add the following below this CDDL HEADER, with the fields
015: * enclosed by brackets "[]" replaced with your own identifying information:
016: * Portions Copyright [yyyy] [name of copyright owner]
017: */
018:
019: package com.noelios.restlet.util;
020:
021: import java.io.IOException;
022: import java.util.Map;
023: import java.util.logging.Level;
024: import java.util.logging.Logger;
025:
026: import org.restlet.data.CharacterSet;
027: import org.restlet.data.Form;
028: import org.restlet.data.Parameter;
029: import org.restlet.data.Reference;
030: import org.restlet.resource.Representation;
031:
032: /**
033: * Representation of a Web form containing submitted parameters.
034: *
035: * @author Jerome Louvel (contact@noelios.com)
036: */
037: public class FormUtils {
038: /**
039: * Parses a query into a given form.
040: *
041: * @param logger
042: * The logger.
043: * @param form
044: * The target form.
045: * @param query
046: * Query string.
047: * @param characterSet
048: * The supported character encoding.
049: */
050: public static void parseQuery(Logger logger, Form form,
051: String query, CharacterSet characterSet) {
052: FormReader fr = null;
053: try {
054: fr = new FormReader(logger, query, characterSet);
055: } catch (IOException ioe) {
056: if (logger != null)
057: logger
058: .log(
059: Level.WARNING,
060: "Unable to create a form reader. Parsing aborted.",
061: ioe);
062: }
063:
064: if (fr != null) {
065: fr.addParameters(form);
066: }
067: }
068:
069: /**
070: * Parses a post into a given form.
071: *
072: * @param logger
073: * The logger.
074: * @param form
075: * The target form.
076: * @param post
077: * The posted form.
078: */
079: public static void parsePost(Logger logger, Form form,
080: Representation post) {
081: if (post.isAvailable()) {
082: FormReader fr = null;
083: try {
084: fr = new FormReader(logger, post);
085: } catch (IOException ioe) {
086: if (logger != null)
087: logger
088: .log(
089: Level.WARNING,
090: "Unable to create a form reader. Parsing aborted.",
091: ioe);
092: }
093:
094: if (fr != null) {
095: fr.addParameters(form);
096: }
097: } else {
098: throw new IllegalStateException(
099: "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");
100: }
101: }
102:
103: /**
104: * Reads the parameters whose name is a key in the given map.<br/> If a
105: * matching parameter is found, its value is put in the map.<br/> If
106: * multiple values are found, a list is created and set in the map.
107: *
108: * @param logger
109: * The logger.
110: * @param query
111: * The query string.
112: * @param parameters
113: * The parameters map controlling the reading.
114: * @param characterSet
115: * The supported character encoding.
116: */
117: public static void getParameters(Logger logger, String query,
118: Map<String, Object> parameters, CharacterSet characterSet)
119: throws IOException {
120: new FormReader(logger, query, characterSet)
121: .readParameters(parameters);
122: }
123:
124: /**
125: * Reads the parameters whose name is a key in the given map.<br/> If a
126: * matching parameter is found, its value is put in the map.<br/> If
127: * multiple values are found, a list is created and set in the map.
128: *
129: * @param logger
130: * The logger.
131: * @param post
132: * The web form representation.
133: * @param parameters
134: * The parameters map controlling the reading.
135: */
136: public static void getParameters(Logger logger,
137: Representation post, Map<String, Object> parameters)
138: throws IOException {
139: if (!post.isAvailable()) {
140: throw new IllegalStateException(
141: "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");
142: } else {
143: new FormReader(logger, post).readParameters(parameters);
144: }
145: }
146:
147: /**
148: * Reads the first parameter with the given name.
149: *
150: * @param logger
151: * The logger.
152: * @param query
153: * The query string.
154: * @param name
155: * The parameter name to match.
156: * @param characterSet
157: * The supported character encoding.
158: * @return The parameter.
159: * @throws IOException
160: */
161: public static Parameter getFirstParameter(Logger logger,
162: String query, String name, CharacterSet characterSet)
163: throws IOException {
164: return new FormReader(logger, query, characterSet)
165: .readFirstParameter(name);
166: }
167:
168: /**
169: * Reads the first parameter with the given name.
170: *
171: * @param logger
172: * The logger.
173: * @param post
174: * The web form representation.
175: * @param name
176: * The parameter name to match.
177: * @return The parameter.
178: * @throws IOException
179: */
180: public static Parameter getFirstParameter(Logger logger,
181: Representation post, String name) throws IOException {
182: if (!post.isAvailable()) {
183: throw new IllegalStateException(
184: "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");
185: } else {
186: return new FormReader(logger, post)
187: .readFirstParameter(name);
188: }
189:
190: }
191:
192: /**
193: * Reads the parameters with the given name.<br/> If multiple values are
194: * found, a list is returned created.
195: *
196: * @param logger
197: * The logger.
198: * @param query
199: * The query string.
200: * @param name
201: * The parameter name to match.
202: * @param characterSet
203: * The supported character encoding.
204: * @return The parameter value or list of values.
205: */
206: public static Object getParameter(Logger logger, String query,
207: String name, CharacterSet characterSet) throws IOException {
208: return new FormReader(logger, query, characterSet)
209: .readParameter(name);
210: }
211:
212: /**
213: * Reads the parameters with the given name.<br/> If multiple values are
214: * found, a list is returned created.
215: *
216: * @param logger
217: * The logger.
218: * @param form
219: * The web form representation.
220: * @param name
221: * The parameter name to match.
222: * @return The parameter value or list of values.
223: */
224: public static Object getParameter(Logger logger,
225: Representation form, String name) throws IOException {
226: if (!form.isAvailable()) {
227: throw new IllegalStateException(
228: "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");
229: } else {
230: return new FormReader(logger, form).readParameter(name);
231: }
232: }
233:
234: /**
235: * Creates a parameter.
236: *
237: * @param name
238: * The parameter name buffer.
239: * @param value
240: * The parameter value buffer (can be null).
241: * @param characterSet
242: * The supported character encoding.
243: * @return The created parameter.
244: * @throws IOException
245: */
246: public static Parameter create(CharSequence name,
247: CharSequence value, CharacterSet characterSet)
248: throws IOException {
249: Parameter result = null;
250:
251: if (name != null) {
252: if (value != null) {
253: result = new Parameter(Reference.decode(
254: name.toString(), characterSet), Reference
255: .decode(value.toString(), characterSet));
256: } else {
257: result = new Parameter(Reference.decode(
258: name.toString(), characterSet), null);
259: }
260: }
261:
262: return result;
263: }
264: }
|