KickJava   Java API By Example, From Geeks To Geeks.

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


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 package org.objectweb.jonathan.apis.protocols;
28
29 import org.objectweb.jonathan.apis.kernel.Context;
30 import org.objectweb.jonathan.apis.kernel.JonathanException;
31 import org.objectweb.jonathan.apis.binding.BindException;
32
33 /**
34  * A session identifier represents an exported session. In other words, it is a
35  * {@link org.objectweb.jonathan.model.name name}, managed by a specific
36  * {@link org.objectweb.jonathan.model.naming_context naming context} of type
37  * {@link Protocol Protocol}, and representing a {@link Session_Low session}.
38  * <p>
39  * The internal structure of a session identifier
40  * is protocol specific: each protocol may define its own SessionIdentifier type
41  * so that it can contain protocol specific information: host name, port...
42  * <p>
43  * Session identifiers are created when "server" objects are exported, and
44  * can typically be encoded in
45  * {@link org.objectweb.jonathan.apis.binding.Identifier identifiers}. On the
46  * "client" side, they can be decoded and used to establish communication channels.
47  *
48  * @see Protocol
49  */
50 public interface SessionIdentifier {
51
52     /**
53      * Returns the protocol that created this session identifier.
54      *
55      * @return the protocol that created this session identifier.
56      */
57     Protocol getProtocol();
58
59     /**
60      * Unexporting a session identifier means that the target session identifier
61      * no longer designates the session it was created for. A session
62      * identifier must no longer be used after it has been "unexported".
63      */
64     void unexport();
65
66     /**
67      * Returns a local session representing the session designated by the provided
68      * lower session interface.
69      * <p>
70      * This operation is used by a protocol to establish a communication channel
71      * to the session specified by the target session identifier. The provided lower
72      * session interface is used to receive messages using the opened channel.
73      *
74      * @param hls a session to receive messages on the opened communication channel;
75      * @return a session to send messages to the remote session.
76      * @exception BindException if the bind process fails.
77      * @exception JonathanException if something else goes wrong.
78      * @see org.objectweb.jonathan.model.binder#bind(org.objectweb.jonathan.model.name)
79      */
80     Session_High bind(Session_Low hls)
81     throws BindException, JonathanException;
82
83
84     /**
85      * Return the session identifiers corresponding to the lower level
86      * protocol layers, if any.
87      *
88      * @return the session identifiers corresponding to the lower level
89      * protocol layers, if any.
90      * @throws JonathanException if something goes wrong.
91      */
92     SessionIdentifier[] next() throws JonathanException;
93
94
95     /**
96      * What kind of protocol does this session identifier relate to?
97      *
98      * @return the kind of protocol this session identifier relates to.
99      */
100     int getProtocolId();
101
102     /**
103      * Yield info about this session, as a Context.
104      *
105      * @return info about this session, as a Context.
106      * @throws JonathanException if something goes wrong.
107      */
108     Context getInfo() throws JonathanException;
109
110     /**
111      * Return true if the target identifier corresponds to a local
112      * connection.
113      *
114      * @return true if the target identifier corresponds to a local
115      * connection.
116      */
117     boolean isLocal();
118 }
119
Popular Tags