KickJava   Java API By Example, From Geeks To Geeks.

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


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 java.util.Properties JavaDoc;
31
32 import org.objectweb.jonathan.apis.kernel.JonathanException;
33 import org.objectweb.jonathan.apis.kernel.Context;
34 import org.objectweb.jonathan.apis.protocols.ProtocolGraph;
35
36 /**
37  * The protocol abstraction represents protocols like TCP, IP or
38  * GIOP. A protocol is a
39  * {@link org.objectweb.jonathan.model.naming_context naming context}
40  * that only deals with a specific family of interfaces -- called
41  * {@link Session_Low sessions} --, and
42  * manages names -- called {@link SessionIdentifier session identifiers} -- to
43  * designate these interfaces. A protocol is actually a
44  * {@link org.objectweb.jonathan.model.binder binder},
45  * since it may give access to the interfaces it identifies.
46  * <p>
47  * The {@link Protocol Protocol}, and {@link ProtocolGraph ProtocolGraph}
48  * abstractions have been designed in Jonathan to allow the creation of
49  * arbitrary protocol stacks, or even graphs.
50  * <p>
51  * The first step in this process is the creation of a protocol graph that will
52  * represent the expected protocol structure. Methods to create such graphs
53  * must be provided by protocols. A protocol graph is a directed (acyclic)
54  * graph composed of protocol-specific nodes, and describing a path to be
55  * followed by messages when they are sent over the net, or received. Each node
56  * has a protocol-specific arity.
57  * <p>
58  * Imagine for instance that you want to build a stack with
59  * the GIOP protocol on top of TCP/IP. You need first to create a graph reduced
60  * to one TCP/IP node (by calling the appropriate method on the TCP/IP
61  * protocol), and then to extend it with a GIOP node pointing to the TCP/IP node
62  * you have just obtained: The GIOP layer
63  * is not designed to issue requests over a network, and thus expects to issue its
64  * requests to a lower layer. The GIOP nodes are built using a protocol graph
65  * representing that lower layer. Note that nothing would forbid a different
66  * architecture, with possibly two graphs representing two different lower
67  * layers, one used to issue one-way requests, and the other for two way
68  * requests.
69  * <p>
70  * When graphs are created, it is also possible to specify additional
71  * information: for instance, the TCP/IP protocol lets you specify a preferred
72  * port number. That's why there is no generic <tt>newProtocolGraph</tt>
73  * operation: the structure of a node and the information to store in it are
74  * very dependent on the specific protocol used.
75  * <p>
76  * Once you have obtained a specific protocol graph, you
77  * can use it to {@link ProtocolGraph#export(Session_Low) export} an interface of a
78  * specific type: {@link Session_Low Session_Low}. This provides you with a
79  * session identifier, which is a
80  * {@link org.objectweb.jonathan.model.name name} for the exported
81  * interface. You only need to call the <tt>export</tt> method on the root of
82  * the protocol graph: The appropriate calls will be recursively issued on its
83  * sub-graphs.
84  * <p>
85  * Information contained in this session identifier may be tranmitted over the
86  * network, and a copy of the session identifier re-constructed on a different
87  * machine (using the appropriate methods provided by protocols). To be able to
88  * access the exported interface, you will have to call the
89  * {@link SessionIdentifier#bind(Session_Low) bind} operation to obtain a
90  * session of type {@link Session_High Session_High}, that will let you send
91  * messages to the exported session.
92  */
93 public interface Protocol {
94    /**
95     * Returns true if the target protocol is an invocation protocol.
96     * <p>
97     * An invocation protocol is a protocol able to handle <i>invocations</i>, i.e.,
98     * requests expecting a reply. In practice, this means that calls to the
99     * {@link Session_High#prepareInvocation(Marshaller) prepareInvocation} method
100     * on sessions obtained from the target protocol will not raise an
101     * {@link org.objectweb.jonathan.apis.kernel.InternalException
102     * InternalException}, but perform the appropriate work.
103     *
104     * @return true if the target protocol is an invocation protocol.
105     */
106     public boolean isAnInvocationProtocol();
107
108     /**
109      * Creates a new protocol graph with a number of given sub
110      * protocol graphs.
111      * @param subgraphs the lower-level graphs
112      * @param hints the information req'd to build the graph
113      * @return a new ProtocolGraph
114      * @exception JonathanException if the hints or the subgraphs are
115      * invalid for this protocol
116      */
117      ProtocolGraph createProtocolGraph(ProtocolGraph[] subgraphs, Context hints) throws JonathanException;
118
119     /**
120      * Creates a new session identifier with the provided info.
121      *
122      * @param info information to create the session identifier.
123      * @param next session identifiers of the lower sessions?
124      * @return the created session identifier.
125      * @throws JonathanException if something goes wrong.
126      */
127     SessionIdentifier createSessionIdentifier(Properties JavaDoc info, SessionIdentifier[] next) throws JonathanException;
128 }
129
Popular Tags