← Back to branch summary

~ubuntu-branches/ubuntu/saucy/restlet/saucy

« back to all changes in this revision

Viewing changes to org.restlet/src/org/restlet/data/Form.java

  • Committer: Package Import Robot
  • Author(s): James Page
  • Date: 2012-06-11 16:25:45 UTC
  • Revision ID: package-import@ubuntu.com-20120611162545-5w2o0resi5y3pybc
Tags: upstream-2.0.14
Import upstream version 2.0.14

Show diffs side-by-side

added added

removed removed

Lines of Context:
org.restlet/src/org/restlet/data/Form.java
 
1
/**
 
2
 * Copyright 2005-2012 Restlet S.A.S.
 
3
 * 
 
4
 * The contents of this file are subject to the terms of one of the following
 
5
 * open source licenses: Apache 2.0 or LGPL 3.0 or LGPL 2.1 or CDDL 1.0 or EPL
 
6
 * 1.0 (the "Licenses"). You can select the license that you prefer but you may
 
7
 * not use this file except in compliance with one of these Licenses.
 
8
 * 
 
9
 * You can obtain a copy of the Apache 2.0 license at
 
10
 * http://www.opensource.org/licenses/apache-2.0
 
11
 * 
 
12
 * You can obtain a copy of the LGPL 3.0 license at
 
13
 * http://www.opensource.org/licenses/lgpl-3.0
 
14
 * 
 
15
 * You can obtain a copy of the LGPL 2.1 license at
 
16
 * http://www.opensource.org/licenses/lgpl-2.1
 
17
 * 
 
18
 * You can obtain a copy of the CDDL 1.0 license at
 
19
 * http://www.opensource.org/licenses/cddl1
 
20
 * 
 
21
 * You can obtain a copy of the EPL 1.0 license at
 
22
 * http://www.opensource.org/licenses/eclipse-1.0
 
23
 * 
 
24
 * See the Licenses for the specific language governing permissions and
 
25
 * limitations under the Licenses.
 
26
 * 
 
27
 * Alternatively, you can obtain a royalty free commercial license with less
 
28
 * limitations, transferable or non-transferable, directly at
 
29
 * http://www.restlet.com/products/restlet-framework
 
30
 * 
 
31
 * Restlet is a registered trademark of Restlet S.A.S.
 
32
 */
 
33
 
 
34
package org.restlet.data;
 
35
 
 
36
import java.io.IOException;
 
37
import java.util.List;
 
38
 
 
39
import org.restlet.engine.util.FormUtils;
 
40
import org.restlet.representation.Representation;
 
41
import org.restlet.representation.StringRepresentation;
 
42
import org.restlet.util.Series;
 
43
 
 
44
/**
 
45
 * Form which is a specialized modifiable list of parameters.
 
46
 * 
 
47
 * @see <a
 
48
 *      href="http://wiki.restlet.org/docs_2.0/13-restlet/27-restlet/330-restlet/58-restlet.html">User
 
49
 *      Guide - Getting parameter values</a>
 
50
 * @author Jerome Louvel
 
51
 */
 
52
public class Form extends Series<Parameter> {
 
53
    /**
 
54
     * Empty constructor.
 
55
     */
 
56
    public Form() {
 
57
        super();
 
58
    }
 
59
 
 
60
    /**
 
61
     * Constructor.
 
62
     * 
 
63
     * @param initialCapacity
 
64
     *            The initial list capacity.
 
65
     */
 
66
    public Form(int initialCapacity) {
 
67
        super(initialCapacity);
 
68
    }
 
69
 
 
70
    /**
 
71
     * Constructor.
 
72
     * 
 
73
     * @param delegate
 
74
     *            The delegate list.
 
75
     */
 
76
    public Form(List<Parameter> delegate) {
 
77
        super(delegate);
 
78
    }
 
79
 
 
80
    /**
 
81
     * Constructor.
 
82
     * 
 
83
     * @param webForm
 
84
     *            The URL encoded Web form.
 
85
     * @throws IOException
 
86
     */
 
87
    public Form(Representation webForm) {
 
88
        FormUtils.parse(this, webForm);
 
89
    }
 
90
 
 
91
    /**
 
92
     * Constructor. Uses UTF-8 as the character set for encoding non-ASCII
 
93
     * characters.
 
94
     * 
 
95
     * @param queryString
 
96
     *            The Web form parameters as a string.
 
97
     * @throws IOException
 
98
     */
 
99
    public Form(String queryString) {
 
100
        this(queryString, CharacterSet.UTF_8);
 
101
    }
 
102
 
 
103
    /**
 
104
     * Constructor. Uses UTF-8 as the character set for encoding non-ASCII
 
105
     * characters.
 
106
     * 
 
107
     * @param parametersString
 
108
     *            The parameters string to parse.
 
109
     * @param separator
 
110
     *            The separator character to append between parameters.
 
111
     * @throws IOException
 
112
     */
 
113
    public Form(String parametersString, char separator) {
 
114
        this(parametersString, CharacterSet.UTF_8, separator);
 
115
    }
 
116
 
 
117
    /**
 
118
     * Constructor.
 
119
     * 
 
120
     * @param queryString
 
121
     *            The Web form parameters as a string.
 
122
     * @param characterSet
 
123
     *            The supported character encoding.
 
124
     * @throws IOException
 
125
     */
 
126
    public Form(String queryString, CharacterSet characterSet) {
 
127
        this(queryString, characterSet, '&');
 
128
    }
 
129
 
 
130
    /**
 
131
     * Constructor.
 
132
     * 
 
133
     * @param parametersString
 
134
     *            The parameters string to parse.
 
135
     * @param characterSet
 
136
     *            The supported character encoding.
 
137
     * @param separator
 
138
     *            The separator character to append between parameters.
 
139
     * @throws IOException
 
140
     */
 
141
    public Form(String parametersString, CharacterSet characterSet,
 
142
            char separator) {
 
143
        FormUtils.parse(this, parametersString, characterSet, true, separator);
 
144
    }
 
145
 
 
146
    @Override
 
147
    public Parameter createEntry(String name, String value) {
 
148
        return new Parameter(name, value);
 
149
    }
 
150
 
 
151
    @Override
 
152
    public Series<Parameter> createSeries(List<Parameter> delegate) {
 
153
        if (delegate != null) {
 
154
            return new Form(delegate);
 
155
        }
 
156
 
 
157
        return new Form();
 
158
    }
 
159
 
 
160
    /**
 
161
     * Encodes the form using the standard URI encoding mechanism and the UTF-8
 
162
     * character set.
 
163
     * 
 
164
     * @return The encoded form.
 
165
     * @throws IOException
 
166
     */
 
167
    public String encode() throws IOException {
 
168
        return encode(CharacterSet.UTF_8);
 
169
    }
 
170
 
 
171
    /**
 
172
     * URL encodes the form. The '&' character is used as a separator.
 
173
     * 
 
174
     * @param characterSet
 
175
     *            The supported character encoding.
 
176
     * @return The encoded form.
 
177
     * @throws IOException
 
178
     */
 
179
    public String encode(CharacterSet characterSet) throws IOException {
 
180
        return encode(characterSet, '&');
 
181
    }
 
182
 
 
183
    /**
 
184
     * URL encodes the form.
 
185
     * 
 
186
     * @param characterSet
 
187
     *            The supported character encoding.
 
188
     * @param separator
 
189
     *            The separator character to append between parameters.
 
190
     * @return The encoded form.
 
191
     * @throws IOException
 
192
     */
 
193
    public String encode(CharacterSet characterSet, char separator)
 
194
            throws IOException {
 
195
        final StringBuilder sb = new StringBuilder();
 
196
        for (int i = 0; i < size(); i++) {
 
197
            if (i > 0) {
 
198
                sb.append(separator);
 
199
            }
 
200
            get(i).encode(sb, characterSet);
 
201
        }
 
202
 
 
203
        return sb.toString();
 
204
    }
 
205
 
 
206
    /**
 
207
     * Formats the form as a matrix path string. Uses UTF-8 as the character set
 
208
     * for encoding non-ASCII characters.
 
209
     * 
 
210
     * @return The form as a matrix string.
 
211
     * @see <a href="http://www.w3.org/DesignIssues/MatrixURIs.html">Matrix URIs
 
212
     *      by Tim Berners Lee</a>
 
213
     */
 
214
    public String getMatrixString() {
 
215
        return getMatrixString(CharacterSet.UTF_8);
 
216
    }
 
217
 
 
218
    /**
 
219
     * Formats the form as a query string.
 
220
     * 
 
221
     * @param characterSet
 
222
     *            The supported character encoding.
 
223
     * @return The form as a matrix string.
 
224
     * @see <a href="http://www.w3.org/DesignIssues/MatrixURIs.html">Matrix URIs
 
225
     *      by Tim Berners Lee</a>
 
226
     */
 
227
    public String getMatrixString(CharacterSet characterSet) {
 
228
        try {
 
229
            return encode(characterSet, ';');
 
230
        } catch (IOException ioe) {
 
231
            return null;
 
232
        }
 
233
    }
 
234
 
 
235
    /**
 
236
     * Formats the form as a query string. Uses UTF-8 as the character set for
 
237
     * encoding non-ASCII characters.
 
238
     * 
 
239
     * @return The form as a query string.
 
240
     */
 
241
    public String getQueryString() {
 
242
        return getQueryString(CharacterSet.UTF_8);
 
243
    }
 
244
 
 
245
    /**
 
246
     * Formats the form as a query string.
 
247
     * 
 
248
     * @param characterSet
 
249
     *            The supported character encoding.
 
250
     * @return The form as a query string.
 
251
     */
 
252
    public String getQueryString(CharacterSet characterSet) {
 
253
        try {
 
254
            return encode(characterSet);
 
255
        } catch (IOException ioe) {
 
256
            return null;
 
257
        }
 
258
    }
 
259
 
 
260
    /**
 
261
     * Returns the form as a Web representation
 
262
     * (MediaType.APPLICATION_WWW_FORM). Uses UTF-8 as the character set for
 
263
     * encoding non-ASCII characters.
 
264
     * 
 
265
     * @return The form as a Web representation.
 
266
     */
 
267
    public Representation getWebRepresentation() {
 
268
        return getWebRepresentation(CharacterSet.UTF_8);
 
269
    }
 
270
 
 
271
    /**
 
272
     * Returns the form as a Web representation
 
273
     * (MediaType.APPLICATION_WWW_FORM).
 
274
     * 
 
275
     * @param characterSet
 
276
     *            The supported character encoding.
 
277
     * @return The form as a Web representation.
 
278
     */
 
279
    public Representation getWebRepresentation(CharacterSet characterSet) {
 
280
        return new StringRepresentation(getQueryString(characterSet),
 
281
                MediaType.APPLICATION_WWW_FORM, null, characterSet);
 
282
    }
 
283
 
 
284
}