KickJava   Java API By Example, From Geeks To Geeks.

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


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: 2.0
20  *
21  * Contact: jonathan@objectweb.org
22  *
23  * Author: Bruno Dumant
24  *
25  */
26
27
28 package org.objectweb.jonathan.apis.protocols;
29
30 import org.objectweb.jonathan.apis.kernel.JonathanException;
31 import org.objectweb.jonathan.apis.presentation.Marshaller;
32
33 /**
34  * <code>Session_High</code> is the type of sessions used to send messages down
35  * to the network; A <code>Session_High</code> is usually a surrogate for
36  * a session of type {@link Session_Low Session_Low} exported to a protocol and
37  * represented by an {@link SessionIdentifier session identifier}.
38  * <p>
39  * Sessions represent handles on particular communication channels: A session
40  * object is dynamically created by a protocol, and lets messages be sent and
41  * received through the communication channel it represents, using that
42  * protocol. Sessions have {@link Session_High higher} and {@link Session_Low lower}
43  * interfaces, respectively used to send messages down and up a protocol stack.
44  * <p>
45  * Usually, a <code>Session_High</code> instance is obtained using the
46  * {@link SessionIdentifier#bind(Session_Low) bind} operation on a session
47  * identifier representing a {@link Session_Low Session_Low} interface: it is
48  * thus a surrogate, or a proxy, for that interface.
49  */
50 public interface Session_High {
51
52    /**
53     * Lets the target session write its own headers into the provided message
54     * (one-way case).
55     * <p>
56     * Protocols usually need to add headers in the front of messages before
57     * sending them down the net. It may be much more efficient to add these headers
58     * <i>before</i> the actual message is written. The <code>prepare</code> (and
59     * {@link #prepareInvocation(Marshaller) prepareInvocation} methods are
60     * provided for this purpose. Therefore, an entity wishing to send a message
61     * down a protocol stack must first prepare that message by invoking the
62     * appropriate method (unless a call to {@link #direct() direct} returns true),
63     * and then write its own data to the message.
64     * <p>
65     * The <code>prepare</code> method must only be used to prepare messages with a
66     * one-way semantics (no reply expected); If a reply is expected, use
67     * {@link #prepareInvocation(Marshaller) prepareInvocation} instead.
68     *
69     * @param m a marshaller representing the message
70     * @exception JonathanException if something goes wrong.
71     */
72    public void prepare(Marshaller m) throws JonathanException;
73
74    /**
75     * Return false if the {@link #prepare(Marshaller) prepare} or
76     * {@link #prepareInvocation(Marshaller) prepareInvocation} must be used, true
77     * otherwise.
78     * <p>
79     * A true return means that the target protocols headers are added when the
80     * message is sent, and not before. Invoking one of the <code>prepare</code>
81     * methods would in that case return without having changed anything to the
82     * provided marshaler.
83     *
84     * @return true if the <code>prepare</code> methods need not be used.
85     */
86    public boolean direct();
87    
88    /*
89     * Lets the target session write its own headers into the provided message
90     * (two-way case).
91     * <p>
92     * Protocols usually need to add headers in the front of messages before
93     * sending them down the net. It may be much more efficient to add these headers
94     * <i>before</i> the actual message is written. The
95     * <code>prepareInvocation</code>
96     * (and {@link #prepare(Marshaller) prepare} methods are
97     * provided for this purpose. Therefore, an entity wishing to send a message
98     * down a protocol stack must first prepare that message by invoking the
99     * appropriate method (unless a call to {@link #direct() direct} returns true),
100     * and then write its own data to the message.
101     * <p>
102     * The <code>prepareInvocation</code> method must only be used to prepare
103     * messages with a two-ways semantics (a reply is expected); If no reply is
104     * expected, use {@link #prepare(Marshaller) prepare} instead.
105     * This method returns
106     * a {@link ReplyInterface ReplyInterface} that must be used to decode the
107     * reply.
108     *
109     * @param m a marshaller representing the message;
110     * @return a reply interface.
111     * @exception JonathanException if something goes wrong.
112     */
113    public ReplyInterface prepareInvocation(Marshaller m)
114       throws JonathanException;
115    
116
117    /**
118     * Sends the message down the protocol stack.
119     * <p>
120     * The sent message must have been prepared first, unless a call to
121     * {@link #direct() direct} returns true.
122     * <p>
123     * It is the responsibility of the recipient of the message to
124     * {@link Marshaller#close() close} it.
125     *
126     * @param m the message to send;
127     * @exception JonathanException if something goes wrong.
128     * @see #prepareInvocation(Marshaller)
129     * @see #prepare(Marshaller)
130     */
131    public void send(Marshaller m)
132       throws JonathanException;
133    
134    /**
135     * Closes the session, letting the associated resources be released or
136     * reused.
137     * <p>
138     * Sessions may have an exclusive access to a communication resource. It is
139     * thus very important to ensure that they are properly closed if they are no
140     * longer in use.
141     */
142    public void close();
143 }
144
Popular Tags