1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19 package net.jini.jeri;
20
21 import java.io.InputStream;
22 import java.io.OutputStream;
23 import java.util.Collection;
24 import net.jini.core.constraint.ConstraintAlternatives;
25 import net.jini.core.constraint.Delegation;
26 import net.jini.core.constraint.Integrity;
27 import net.jini.core.constraint.InvocationConstraints;
28 import net.jini.io.UnsupportedConstraintException;
29 import net.jini.security.AuthenticationPermission;
30
31 /**
32 * Represents a request that is being received and the corresponding
33 * response to be sent in reply.
34 *
35 * <p>An <code>InboundRequest</code> can be used to read in the
36 * contents of the request and write out the response.
37 *
38 * @author Sun Microsystems, Inc.
39 * @see OutboundRequest
40 * @see RequestDispatcher
41 * @since 2.0
42 **/
43 public interface InboundRequest {
44
45 /**
46 * Verifies that the current security context has all of the
47 * security permissions necessary to receive this request.
48 *
49 * <p>This method should be used when a particular shared
50 * mechanism is used to receive requests for a variety of
51 * interested parties, each with potentially different security
52 * permissions possibly more limited than those granted to the
53 * code managing the shared mechanism, so that the managing code
54 * can verify proper access control for each party.
55 *
56 * <p>For example, a TCP-based <code>InboundRequest</code>
57 * implementation typically implements this method by invoking the
58 * {@link SecurityManager#checkAccept checkAccept} method of the
59 * current security manager (if any) with the client's host
60 * address and TCP port. An implementation that supports
61 * authentication typically checks that the current security
62 * context has the necessary {@link AuthenticationPermission} with
63 * <code>accept</code> action.
64 *
65 * @throws SecurityException if the current security context does
66 * not have the permissions necessary to receive this request
67 **/
68 void checkPermissions();
69
70 /**
71 * Verifies that this request satisfies the transport layer
72 * aspects of all of the specified requirements, and returns the
73 * requirements that must be at least partially implemented by
74 * higher layers in order to fully satisfy the specified
75 * requirements. This method may also return preferences that
76 * must be at least partially implemented by higher layers in
77 * order to fully satisfy some of the specified preferences.
78 *
79 * <p>For any given constraint, there must be a clear delineation
80 * of which aspects (if any) must be implemented by the transport
81 * layer. This method must not return a constraint (as a
82 * requirement or a preference, directly or as an element of
83 * another constraint) unless this request implements all of those
84 * aspects. Also, this method must not return a constraint for
85 * which all aspects must be implemented by the transport layer.
86 * Most of the constraints in the {@link net.jini.core.constraint}
87 * package must be fully implemented by the transport layer and
88 * thus must not be returned by this method; the one exception is
89 * {@link Integrity}, for which the transport layer is responsible
90 * for the data integrity aspect and higher layers are responsible
91 * for the code integrity aspect.
92 *
93 * <p>For any {@link ConstraintAlternatives} in the specified
94 * constraints, this method should only return a corresponding
95 * constraint if all of the alternatives satisfied by this request
96 * need to be at least partially implemented by higher layers in
97 * order to be fully satisfied.
98 *
99 * <p>The constraints actually in force may cause conditional
100 * constraints to have to be satisfied. For example, if the only
101 * requirement specified is {@link Delegation#YES Delegation.YES}
102 * but the client was in fact authenticated, then the client must
103 * also have delegated to the server.
104 *
105 * <p>The constraints passed to this method may include
106 * constraints based on relative time.
107 *
108 * @param constraints the constraints that must be satisfied
109 *
110 * @return the constraints that must be at least partially
111 * implemented by higher layers
112 *
113 * @throws UnsupportedConstraintException if the transport layer
114 * aspects of any of the specified requirements are not satisfied
115 * by this request
116 *
117 * @throws NullPointerException if <code>constraints</code> is
118 * <code>null</code>
119 **/
120 InvocationConstraints checkConstraints(InvocationConstraints constraints)
121 throws UnsupportedConstraintException;
122
123 /**
124 * Populates the supplied collection with context information
125 * representing this request.
126 *
127 * @param context the context collection to populate
128 *
129 * @throws NullPointerException if <code>context</code> is
130 * <code>null</code>
131 *
132 * @throws UnsupportedOperationException if <code>context</code>
133 * is unmodifiable and if any elements need to be added
134 **/
135 void populateContext(Collection context);
136
137 /**
138 * Returns an <code>InputStream</code> to read the request data
139 * from. The sequence of bytes produced by reading from the
140 * returned stream will be the sequence of bytes received as the
141 * request data. When the entirety of the request has been
142 * successfully read, reading from the stream will indicate an
143 * EOF.
144 *
145 * <p>Invoking the <code>close</code> method of the returned
146 * stream will cause any subsequent read operations on the stream
147 * to fail with an <code>IOException</code>, although it will not
148 * terminate this request as a whole; in particular, the response
149 * may still be subsequently written to the stream returned by the
150 * <code>getResponseOutputStream</code> method. After
151 * <code>close</code> has been invoked on both the returned stream
152 * and the stream returned by
153 * <code>getResponseOutputStream</code>, the implementation may
154 * free all resources associated with this request.
155 *
156 * <p>If this method is invoked more than once, it will always
157 * return the identical stream object that it returned the first
158 * time (although the stream may be in a different state than it
159 * was upon return from the first invocation).
160 *
161 * @return the input stream to read request data from
162 **/
163 InputStream getRequestInputStream();
164
165 /**
166 * Returns an <code>OutputStream</code> to write the response data
167 * to. The sequence of bytes written to the returned stream will
168 * be the sequence of bytes sent as the response.
169 *
170 * <p>After the entirety of the response has been written to the
171 * stream, the stream's <code>close</code> method must be invoked
172 * to ensure complete delivery of the response. It is possible
173 * that none of the data written to the returned stream will be
174 * delivered before <code>close</code> has been invoked (even if
175 * the stream's <code>flush</code> method has been invoked at any
176 * time). Note, however, that some or all of the data written to
177 * the stream may be delivered to (and processed by) the recipient
178 * before the stream's <code>close</code> method has been invoked.
179 *
180 * <p>After the stream's <code>close</code> method has been
181 * invoked, no more data may be written to the stream; writes
182 * subsequent to a <code>close</code> invocation will fail with an
183 * <code>IOException</code>.
184 *
185 * <p>If this method is invoked more than once, it will always
186 * return the identical stream object that it returned the first
187 * time (although the stream may be in a different state than it
188 * was upon return from the first invocation).
189 *
190 * @return the output stream to write response data to
191 **/
192 OutputStream getResponseOutputStream();
193
194 /**
195 * Terminates this request, freeing all associated resources.
196 *
197 * <p>This method may be invoked at any stage of the processing of
198 * the request.
199 *
200 * <p>After this method has been invoked, I/O operations on the
201 * streams returned by the <code>getRequestInputStream</code> and
202 * <code>getResponseOutputStream</code> methods will fail with an
203 * <code>IOException</code>, except some operations that may
204 * succeed because they only affect data in local I/O buffers.
205 *
206 * <p>If this method is invoked before the <code>close</code>
207 * method has been invoked on the stream returned by
208 * <code>getResponseOutputStream</code>, there is no guarantee
209 * that any or none of the data written to the stream so far will
210 * be delivered; the implication of such an invocation of this
211 * method is that the user is no longer interested in the
212 * successful delivery of the response.
213 **/
214 void abort();
215 }