KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > objectweb > jonathan > apis > protocols > ReplySession


1 /***
2  * Jonathan: an Open Distributed Processing Environment
3  * Copyright (C) 1999 France Telecom R&D
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Lesser General Public
7  * License as published by the Free Software Foundation; either
8  * version 2 of the License, or (at your option) any later version.
9  *
10  * This library is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13  * Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public
16  * License along with this library; if not, write to the Free Software
17  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18  *
19  * Release: 3.0
20  *
21  * Contact: jonathan@objectweb.org
22  *
23  * Author: Bruno Dumant
24  * With contributions from:
25  * H. Piccione & S. Thiebaud
26  *
27  */
28
29
30 package org.objectweb.jonathan.apis.protocols;
31
32 import org.objectweb.jonathan.apis.kernel.JonathanException;
33 import org.objectweb.jonathan.apis.presentation.Marshaller;
34
35 /**
36  * A reply session is used by a server to send a reply back to a client.
37  */
38 public interface ReplySession {
39
40    /**
41     * Lets the target session write its own headers into a newly created message
42     * and returns it (standard reply case)
43     * <p>
44     * An entity wishing to send a message as a reply to an invocation must not
45     * create a marshaller on its own and directly
46     * {@link #send(Marshaller) send} it down the protocol stack. Instead, it must
47     * ask the session for a marshaller, into which the session will usually
48     * already have written its specific headers.
49     * <p>
50     * The <code>prepareException</code> method must only be used to prepare
51     * messages corresponding to a non-exceptional reply from the server. If the
52     * reply corresponds to an exception raised by the server, use
53     * {@link #prepareExceptionReply() prepareExceptionReply} instead.
54     *
55     * @return a marshaller to write the reply into;
56     * @exception JonathanException if something goes wrong.
57     */
58    public Marshaller prepareReply() throws JonathanException;
59
60    /**
61     * Lets the target session write its own headers into a newly created message
62     * and returns it (exception case)
63     * <p>
64     * An entity wishing to send a message as a reply to an invocation must not
65     * create a marshaller on its own and directly
66     * {@link #send(Marshaller) send} it down the protocol stack. Instead, it must
67     * ask the session for a marshaller, into which the session will usually
68     * already have written its specific headers.
69     * <p>
70     * The <code>prepareExceptionReply</code> method must only be used to prepare
71     * messages
72     * corresponding to an exception raised by the server.
73     *
74     * @return a marshaller to write the reply into;
75     * @exception JonathanException if something goes wrong.
76     */
77    public Marshaller prepareExceptionReply() throws JonathanException;
78
79
80
81     /**
82     * Lets the target session write its own headers into a newly created message
83     * and returns it (system exception case)
84     * <p>
85     * An entity wishing to send a message as a reply to an invocation must not
86     * create a marshaller on its own and directly
87     * {@link #send(Marshaller) send} it down the protocol stack. Instead, it must
88     * ask the session for a marshaller, into which the session will usually
89     * already have written its specific headers.
90     * <p>
91     * The <code>prepareSystemExceptionReply</code> method must only be used to prepare
92     * messages
93     * corresponding to an system exception raised by the server.
94     *
95     * @return a marshaller to write the reply into;
96     * @exception JonathanException if something goes wrong.
97     */
98    public Marshaller prepareSystemExceptionReply() throws JonathanException;
99
100
101
102     /**
103     * Lets the target session write its own headers into a newly created message
104     * and returns it (location forward case)
105     * <p>
106     * An entity wishing to send a message as a reply to an invocation must not
107     * create a marshaller on its own and directly
108     * {@link #send(Marshaller) send} it down the protocol stack. Instead, it must
109     * ask the session for a marshaller, into which the session will usually
110     * already have written its specific headers.
111     * <p>
112     * The <code>prepareLocationForwardReply</code> method must only be used to prepare
113     * messages corresponding to an location forward message raised by the server.
114     *
115     * @return a marshaller to write the reply into;
116     * @exception JonathanException if something goes wrong.
117     */
118    public Marshaller prepareLocationForwardReply() throws JonathanException;
119
120
121
122    /**
123     * Sends the reply down the protocol stack.
124     * <p>
125     * The sent message must have been obtained by calling the
126     * {@link #prepareReply() prepareReply} or
127     * {@link #prepareExceptionReply() prepareExceptionReply} method.
128     * <p>
129     * It is the responsibility of the recipient of the message to
130     * {@link Marshaller#close() close} it.
131     *
132     * @param m the message to send;
133     * @exception JonathanException if something goes wrong.
134     */
135    public void send(Marshaller m) throws JonathanException;
136    
137    /**
138     * Closes the session, letting the associated resources be released or
139     * reused.
140     * <p>
141     * Sessions may have an exclusive access to a communication resource. It is
142     * thus very important to ensure that they are properly closed if they are no
143     * longer in use.
144     */
145    public void close();
146 }
147
148
149
150
151   
152
Popular Tags