1/*
2 * Copyright (c) 2008-2009, Motorola, Inc.
3 *
4 * All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met:
8 *
9 * - Redistributions of source code must retain the above copyright notice,
10 * this list of conditions and the following disclaimer.
11 *
12 * - Redistributions in binary form must reproduce the above copyright notice,
13 * this list of conditions and the following disclaimer in the documentation
14 * and/or other materials provided with the distribution.
15 *
16 * - Neither the name of the Motorola, Inc. nor the names of its contributors
17 * may be used to endorse or promote products derived from this software
18 * without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
24 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
25 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
26 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
28 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
29 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30 * POSSIBILITY OF SUCH DAMAGE.
31 */
32
33package javax.obex;
34
35/**
36 * The <code>ServerRequestHandler</code> class defines an event listener that
37 * will respond to OBEX requests made to the server.
38 * <P>
39 * The <code>onConnect()</code>, <code>onSetPath()</code>,
40 * <code>onDelete()</code>, <code>onGet()</code>, and <code>onPut()</code>
41 * methods may return any response code defined in the
42 * <code>ResponseCodes</code> class except for <code>OBEX_HTTP_CONTINUE</code>.
43 * If <code>OBEX_HTTP_CONTINUE</code> or a value not defined in the
44 * <code>ResponseCodes</code> class is returned, the server implementation will
45 * send an <code>OBEX_HTTP_INTERNAL_ERROR</code> response to the client.
46 * <P>
47 * <STRONG>Connection ID and Target Headers</STRONG>
48 * <P>
49 * According to the IrOBEX specification, a packet may not contain a Connection
50 * ID and Target header. Since the Connection ID header is managed by the
51 * implementation, it will not send a Connection ID header, if a Connection ID
52 * was specified, in a packet that has a Target header. In other words, if an
53 * application adds a Target header to a <code>HeaderSet</code> object used in
54 * an OBEX operation and a Connection ID was specified, no Connection ID will be
55 * sent in the packet containing the Target header.
56 * <P>
57 * <STRONG>CREATE-EMPTY Requests</STRONG>
58 * <P>
59 * A CREATE-EMPTY request allows clients to create empty objects on the server.
60 * When a CREATE-EMPTY request is received, the <code>onPut()</code> method will
61 * be called by the implementation. To differentiate between a normal PUT
62 * request and a CREATE-EMPTY request, an application must open the
63 * <code>InputStream</code> from the <code>Operation</code> object passed to the
64 * <code>onPut()</code> method. For a PUT request, the application will be able
65 * to read Body data from this <code>InputStream</code>. For a CREATE-EMPTY
66 * request, there will be no Body data to read. Therefore, a call to
67 * <code>InputStream.read()</code> will return -1.
68 * @hide
69 */
70public class ServerRequestHandler {
71
72    private long mConnectionId;
73
74    /**
75     * Creates a <code>ServerRequestHandler</code>.
76     */
77    protected ServerRequestHandler() {
78        /*
79         * A connection ID of -1 implies there is no conenction ID
80         */
81        mConnectionId = -1;
82    }
83
84    /**
85     * Sets the connection ID header to include in the reply packets.
86     * @param connectionId the connection ID to use; -1 if no connection ID
87     *        should be sent
88     * @throws IllegalArgumentException if <code>id</code> is not in the range
89     *         -1 to 2<sup>32</sup>-1
90     */
91    public void setConnectionId(final long connectionId) {
92        if ((connectionId < -1) || (connectionId > 0xFFFFFFFFL)) {
93            throw new IllegalArgumentException("Illegal Connection ID");
94        }
95        mConnectionId = connectionId;
96    }
97
98    /**
99     * Retrieves the connection ID that is being used in the present connection.
100     * This method will return -1 if no connection ID is being used.
101     * @return the connection id being used or -1 if no connection ID is being
102     *         used
103     */
104    public long getConnectionId() {
105        return mConnectionId;
106    }
107
108    /**
109     * Called when a CONNECT request is received.
110     * <P>
111     * If this method is not implemented by the class that extends this class,
112     * <code>onConnect()</code> will always return an <code>OBEX_HTTP_OK</code>
113     * response code.
114     * <P>
115     * The headers received in the request can be retrieved from the
116     * <code>request</code> argument. The headers that should be sent in the
117     * reply must be specified in the <code>reply</code> argument.
118     * @param request contains the headers sent by the client;
119     *        <code>request</code> will never be <code>null</code>
120     * @param reply the headers that should be sent in the reply;
121     *        <code>reply</code> will never be <code>null</code>
122     * @return a response code defined in <code>ResponseCodes</code> that will
123     *         be returned to the client; if an invalid response code is
124     *         provided, the <code>OBEX_HTTP_INTERNAL_ERROR</code> response code
125     *         will be used
126     */
127    public int onConnect(HeaderSet request, HeaderSet reply) {
128        return ResponseCodes.OBEX_HTTP_OK;
129    }
130
131    /**
132     * Called when a DISCONNECT request is received.
133     * <P>
134     * The headers received in the request can be retrieved from the
135     * <code>request</code> argument. The headers that should be sent in the
136     * reply must be specified in the <code>reply</code> argument.
137     * @param request contains the headers sent by the client;
138     *        <code>request</code> will never be <code>null</code>
139     * @param reply the headers that should be sent in the reply;
140     *        <code>reply</code> will never be <code>null</code>
141     */
142    public void onDisconnect(HeaderSet request, HeaderSet reply) {
143    }
144
145    /**
146     * Called when a SETPATH request is received.
147     * <P>
148     * If this method is not implemented by the class that extends this class,
149     * <code>onSetPath()</code> will always return an
150     * <code>OBEX_HTTP_NOT_IMPLEMENTED</code> response code.
151     * <P>
152     * The headers received in the request can be retrieved from the
153     * <code>request</code> argument. The headers that should be sent in the
154     * reply must be specified in the <code>reply</code> argument.
155     * @param request contains the headers sent by the client;
156     *        <code>request</code> will never be <code>null</code>
157     * @param reply the headers that should be sent in the reply;
158     *        <code>reply</code> will never be <code>null</code>
159     * @param backup <code>true</code> if the client requests that the server
160     *        back up one directory before changing to the path described by
161     *        <code>name</code>; <code>false</code> to apply the request to the
162     *        present path
163     * @param create <code>true</code> if the path should be created if it does
164     *        not already exist; <code>false</code> if the path should not be
165     *        created if it does not exist and an error code should be returned
166     * @return a response code defined in <code>ResponseCodes</code> that will
167     *         be returned to the client; if an invalid response code is
168     *         provided, the <code>OBEX_HTTP_INTERNAL_ERROR</code> response code
169     *         will be used
170     */
171    public int onSetPath(HeaderSet request, HeaderSet reply, boolean backup, boolean create) {
172
173        return ResponseCodes.OBEX_HTTP_NOT_IMPLEMENTED;
174    }
175
176    /**
177     * Called when a DELETE request is received.
178     * <P>
179     * If this method is not implemented by the class that extends this class,
180     * <code>onDelete()</code> will always return an
181     * <code>OBEX_HTTP_NOT_IMPLEMENTED</code> response code.
182     * <P>
183     * The headers received in the request can be retrieved from the
184     * <code>request</code> argument. The headers that should be sent in the
185     * reply must be specified in the <code>reply</code> argument.
186     * @param request contains the headers sent by the client;
187     *        <code>request</code> will never be <code>null</code>
188     * @param reply the headers that should be sent in the reply;
189     *        <code>reply</code> will never be <code>null</code>
190     * @return a response code defined in <code>ResponseCodes</code> that will
191     *         be returned to the client; if an invalid response code is
192     *         provided, the <code>OBEX_HTTP_INTERNAL_ERROR</code> response code
193     *         will be used
194     */
195    public int onDelete(HeaderSet request, HeaderSet reply) {
196        return ResponseCodes.OBEX_HTTP_NOT_IMPLEMENTED;
197    }
198
199    /**
200     * Called when a ABORT request is received.
201     */
202    public int onAbort(HeaderSet request, HeaderSet reply) {
203        return ResponseCodes.OBEX_HTTP_NOT_IMPLEMENTED;
204    }
205
206    /**
207     * Called when a PUT request is received.
208     * <P>
209     * If this method is not implemented by the class that extends this class,
210     * <code>onPut()</code> will always return an
211     * <code>OBEX_HTTP_NOT_IMPLEMENTED</code> response code.
212     * <P>
213     * If an ABORT request is received during the processing of a PUT request,
214     * <code>op</code> will be closed by the implementation.
215     * @param operation contains the headers sent by the client and allows new
216     *        headers to be sent in the reply; <code>op</code> will never be
217     *        <code>null</code>
218     * @return a response code defined in <code>ResponseCodes</code> that will
219     *         be returned to the client; if an invalid response code is
220     *         provided, the <code>OBEX_HTTP_INTERNAL_ERROR</code> response code
221     *         will be used
222     */
223    public int onPut(Operation operation) {
224        return ResponseCodes.OBEX_HTTP_NOT_IMPLEMENTED;
225    }
226
227    /**
228     * Called when a GET request is received.
229     * <P>
230     * If this method is not implemented by the class that extends this class,
231     * <code>onGet()</code> will always return an
232     * <code>OBEX_HTTP_NOT_IMPLEMENTED</code> response code.
233     * <P>
234     * If an ABORT request is received during the processing of a GET request,
235     * <code>op</code> will be closed by the implementation.
236     * @param operation contains the headers sent by the client and allows new
237     *        headers to be sent in the reply; <code>op</code> will never be
238     *        <code>null</code>
239     * @return a response code defined in <code>ResponseCodes</code> that will
240     *         be returned to the client; if an invalid response code is
241     *         provided, the <code>OBEX_HTTP_INTERNAL_ERROR</code> response code
242     *         will be used
243     */
244    public int onGet(Operation operation) {
245        return ResponseCodes.OBEX_HTTP_NOT_IMPLEMENTED;
246    }
247
248    /**
249     * Called when this object attempts to authenticate a client and the
250     * authentication request fails because the response digest in the
251     * authentication response header was wrong.
252     * <P>
253     * If this method is not implemented by the class that extends this class,
254     * this method will do nothing.
255     * @param userName the user name returned in the authentication response;
256     *        <code>null</code> if no user name was provided in the response
257     */
258    public void onAuthenticationFailure(byte[] userName) {
259    }
260
261    /**
262     * Called by ServerSession to update the status of current transaction
263     * <P>
264     * If this method is not implemented by the class that extends this class,
265     * this method will do nothing.
266     */
267    public void updateStatus(String message) {
268    }
269
270    /**
271     * Called when session is closed.
272     * <P>
273     * If this method is not implemented by the class that extends this class,
274     * this method will do nothing.
275     */
276    public void onClose() {
277    }
278}
279