1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
/*
* Request.java February 2001
*
* Copyright (C) 2001, Niall Gallagher <niallg@users.sf.net>
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
* implied. See the License for the specific language governing
* permissions and limitations under the License.
*/
package org.simpleframework.http;
import java.io.IOException;
import java.io.InputStream;
import java.net.InetSocketAddress;
import java.nio.channels.ReadableByteChannel;
import java.util.List;
import java.util.Map;
import org.simpleframework.transport.Certificate;
import org.simpleframework.transport.Channel;
/**
* The <code>Request</code> is used to provide an interface to the
* HTTP entity body and message header. This provides methods that
* allow the entity body to be acquired as a stream, string, or if
* the message is a multipart encoded body, then the individual
* parts of the request body can be acquired.
* <p>
* This can also maintain data during the request lifecycle as well
* as the session lifecycle. A <code>Session</code> is made available
* for convenience. It provides a means for the services to associate
* data with a given client session, which can be retrieved when
* there are subsequent requests sent to the server.
* <p>
* It is important to note that the entity body can be read multiple
* times from the request. Calling <code>getInputStream</code> will
* start reading from the first byte in the body regardless of the
* number of times it is called. This allows POST parameters as well
* as multipart bodies to be read from the stream if desired.
*
* @author Niall Gallagher
*/
public interface Request extends RequestHeader {
/**
* This is used to determine if the request has been transferred
* over a secure connection. If the protocol is HTTPS and the
* content is delivered over SSL then the request is considered
* to be secure. Also the associated response will be secure.
*
* @return true if the request is transferred securely
*/
boolean isSecure();
/**
* This is a convenience method that is used to determine whether
* or not this message has the <code>Connection: close</code>
* header. If the close token is present then this stream is not
* a keep-alive connection. If this has no <code>Connection</code>
* header then the keep-alive status is determined by the HTTP
* version, that is, HTTP/1.1 is keep-alive by default, HTTP/1.0
* is not keep-alive by default.
*
* @return returns true if this has a keep-alive stream
*/
boolean isKeepAlive();
/**
* This is the time in milliseconds when the request was first
* read from the underlying socket. The time represented here
* represents the time collection of this request began. This
* does not necessarily represent the time the bytes arrived as
* as some data may have been buffered before it was parsed.
*
* @return this represents the time the request arrived at
*/
long getRequestTime();
/**
* This provides the underlying channel for the request. It
* contains the TCP socket channel and various other low level
* components. Typically this will only ever be needed when
* there is a need to switch protocols.
*
* @return the underlying channel for this request
*/
Channel getChannel();
/**
* This is used to acquire the SSL certificate used when the
* server is using a HTTPS connection. For plain text connections
* or connections that use a security mechanism other than SSL
* this will be null. This is only available when the connection
* makes specific use of an SSL engine to secure the connection.
*
* @return this returns the associated SSL certificate if any
*/
Certificate getClientCertificate();
/**
* This is used to acquire the remote client address. This can
* be used to acquire both the port and the I.P address for the
* client. It allows the connected clients to be logged and if
* require it can be used to perform course grained security.
*
* @return this returns the client address for this request
*/
InetSocketAddress getClientAddress();
/**
* This can be used to retrieve the response attributes. These can
* be used to keep state with the response when it is passed to
* other systems for processing. Attributes act as a convenient
* model for storing objects associated with the response. This
* also inherits attributes associated with the client connection.
*
* @return the attributes of that have been set on the request
*/
Map getAttributes();
/**
* This is used as a shortcut for acquiring attributes for the
* response. This avoids acquiring the attribute <code>Map</code>
* in order to retrieve the attribute directly from that object.
* The attributes contain data specific to the response.
*
* @param key this is the key of the attribute to acquire
*
* @return this returns the attribute for the specified name
*/
Object getAttribute(Object key);
/**
* This is used to provide quick access to the parameters. This
* avoids having to acquire the request <code>Form</code> object.
* This basically acquires the parameters object and invokes
* the <code>getParameters</code> method with the given name.
*
* @param name this is the name of the parameter value
*/
String getParameter(String name);
/**
* This method is used to acquire a <code>Part</code> from the
* HTTP request using a known name for the part. This is typically
* used when there is a file upload with a multipart POST request.
* All parts that are not files can be acquired as string values
* from the attachment object.
*
* @param name this is the name of the part object to acquire
*
* @return the named part or null if the part does not exist
*/
Part getPart(String name);
/**
* This method is used to get all <code>Part</code> objects that
* are associated with the request. Each attachment contains the
* body and headers associated with it. If the request is not a
* multipart POST request then this will return an empty list.
*
* @return the list of parts associated with this request
*/
List<Part> getParts();
/**
* This is used to get the content body. This will essentially get
* the content from the body and present it as a single string.
* The encoding of the string is determined from the content type
* charset value. If the charset is not supported this will throw
* an exception. Typically only text values should be extracted
* using this method if there is a need to parse that content.
*
* @return this returns the message bytes as an encoded string
*/
String getContent() throws IOException;
/**
* This is used to read the content body. The specifics of the data
* that is read from this <code>InputStream</code> can be determined
* by the <code>getContentLength</code> method. If the data sent by
* the client is chunked then it is decoded, see RFC 2616 section
* 3.6. Also multipart data is available as <code>Part</code> objects
* however the raw content of the multipart body is still available.
*
* @return this returns an input stream containing the message body
*/
InputStream getInputStream() throws IOException;
/**
* This is used to read the content body. The specifics of the data
* that is read from this <code>ReadableByteChannel</code> can be
* determined by the <code>getContentLength</code> method. If the
* data sent by the client is chunked then it is decoded, see RFC
* 2616 section 3.6. This stream will never provide empty reads as
* the content is internally buffered, so this can do a full read.
*
* @return this returns the byte channel used to read the content
*/
ReadableByteChannel getByteChannel() throws IOException;
}
|
