KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > exolab > jms > net > orb > ORB


1 /**
2  * Redistribution and use of this software and associated documentation
3  * ("Software"), with or without modification, are permitted provided
4  * that the following conditions are met:
5  *
6  * 1. Redistributions of source code must retain copyright
7  * statements and notices. Redistributions must also contain a
8  * copy of this document.
9  *
10  * 2. Redistributions in binary form must reproduce the
11  * above copyright notice, this list of conditions and the
12  * following disclaimer in the documentation and/or other
13  * materials provided with the distribution.
14  *
15  * 3. The name "Exolab" must not be used to endorse or promote
16  * products derived from this Software without prior written
17  * permission of Exoffice Technologies. For written permission,
18  * please contact info@exolab.org.
19  *
20  * 4. Products derived from this Software may not be called "Exolab"
21  * nor may "Exolab" appear in their names without prior written
22  * permission of Exoffice Technologies. Exolab is a registered
23  * trademark of Exoffice Technologies.
24  *
25  * 5. Due credit should be given to the Exolab Project
26  * (http://www.exolab.org/).
27  *
28  * THIS SOFTWARE IS PROVIDED BY EXOFFICE TECHNOLOGIES AND CONTRIBUTORS
29  * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
30  * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
31  * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
32  * EXOFFICE TECHNOLOGIES OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
33  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
34  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
35  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
36  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
37  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
38  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
39  * OF THE POSSIBILITY OF SUCH DAMAGE.
40  *
41  * Copyright 2003-2005 (C) Exoffice Technologies Inc. All Rights Reserved.
42  *
43  * $Id: ORB.java,v 1.5 2005/05/27 14:04:01 tanderson Exp $
44  */
45 package org.exolab.jms.net.orb;
46
47 import java.rmi.NoSuchObjectException JavaDoc;
48 import java.rmi.RemoteException JavaDoc;
49 import java.rmi.StubNotFoundException JavaDoc;
50 import java.rmi.server.ExportException JavaDoc;
51 import java.rmi.server.ObjID JavaDoc;
52 import java.util.Map JavaDoc;
53
54 import org.exolab.jms.net.connector.CallerListener;
55 import org.exolab.jms.net.connector.Caller;
56 import org.exolab.jms.net.proxy.Proxy;
57 import org.exolab.jms.net.registry.LocalRegistry;
58 import org.exolab.jms.net.registry.Registry;
59
60
61 /**
62  * The <code>ORB</code> enables objects to be distributed.
63  *
64  * @author <a HREF="mailto:tma@netspace.net.au">Tim Anderson</a>
65  * @version $Revision: 1.5 $ $Date: 2005/05/27 14:04:01 $
66  */
67 public interface ORB {
68
69     /**
70      * Constant that holds the name of the connection property for specifying
71      * the ORB provider URI.
72      */
73     final String JavaDoc PROVIDER_URI
74             = "org.exolab.jms.net.orb.provider.uri";
75
76     /**
77      * Constant that holds the name of the connection property for specifying
78      * the identity of the principal for authenticating the caller to the ORB.
79      * The format of the principal depends on the authentication scheme.
80      */
81     final String JavaDoc SECURITY_PRINCIPAL
82             = "org.exolab.jms.net.orb.security.principal";
83
84     /**
85      * Constant that holds the name of the connection property for specifying
86      * the credentials of the principal for authenticating the caller to the
87      * ORB. The value of the property depends on the authentication scheme.
88      */
89     final String JavaDoc SECURITY_CREDENTIALS
90             = "org.exolab.jms.net.orb.security.credentials";
91
92     /**
93      * Add a route for exported objects.
94      *
95      * @param uri the URI to route
96      * @param toURI the URI to route to
97      * @throws RemoteException for any error
98      */
99     void addRoute(String JavaDoc uri, String JavaDoc toURI) throws RemoteException JavaDoc;
100
101     /**
102      * Returns a reference to the registry service.
103      *
104      * @return the registry service
105      * @throws RemoteException if the service cannot be exported
106      */
107     LocalRegistry getRegistry() throws RemoteException JavaDoc;
108
109     /**
110      * Returns a reference to a remote registry service.
111      *
112      * @param properties the connection properties. May be <code>null</code>.
113      * @return the registry service
114      * @throws RemoteException for any error
115      */
116     Registry getRegistry(Map JavaDoc properties) throws RemoteException JavaDoc;
117
118     /**
119      * Export an object on the default URI.
120      *
121      * @param object the object to export
122      * @return a proxy which may be used to invoke methods on the object
123      * @throws ExportException if the object cannot be exported
124      * @throws StubNotFoundException if the proxy class cannot be found
125      */
126     Proxy exportObject(Object JavaDoc object)
127             throws ExportException JavaDoc, StubNotFoundException JavaDoc;
128
129     /**
130      * Export an object on a specific URI.
131      *
132      * @param object the object to export
133      * @param uri the URI via which connections to the object are made. If
134      * <code>null</code>, the default URI is used.
135      * @return a proxy which may be used to invoke methods on the object
136      * @throws ExportException if the object cannot be exported
137      * @throws StubNotFoundException if the proxy class cannot be found
138      */
139     Proxy exportObject(Object JavaDoc object, String JavaDoc uri)
140             throws ExportException JavaDoc, StubNotFoundException JavaDoc;
141
142     /**
143      * Export an object with a well known identifier on the default URI.
144      *
145      * @param object the object to export
146      * @param objID the well known object identifier
147      * @return a proxy which may be used to invoke methods on the object
148      * @throws ExportException if the object cannot be exported
149      * @throws StubNotFoundException if the proxy class cannot be found
150      */
151     Proxy exportObject(Object JavaDoc object, ObjID JavaDoc objID)
152             throws ExportException JavaDoc, StubNotFoundException JavaDoc;
153
154     /**
155      * Export an object with a well known identifier on a specific URI.
156      *
157      * @param object the object to export
158      * @param objID the well known object identifier
159      * @param uri the URI via which connections to the object are made
160      * @return a proxy which may be used to invoke methods on the object
161      * @throws ExportException if the object cannot be exported
162      * @throws StubNotFoundException if the proxy class cannot be found
163      */
164     Proxy exportObject(Object JavaDoc object, ObjID JavaDoc objID, String JavaDoc uri)
165             throws ExportException JavaDoc, StubNotFoundException JavaDoc;
166
167     /**
168      * Export an object to the current remote caller. Only the remote caller may
169      * perform invocations.
170      *
171      * @param object the object to export
172      * @return a proxy which may be used to invoke methods on the object
173      * @throws ExportException if the object cannot be exported
174      * @throws StubNotFoundException if the proxy class cannot be found
175      */
176     Proxy exportObjectTo(Object JavaDoc object)
177             throws ExportException JavaDoc, StubNotFoundException JavaDoc;
178
179     /**
180      * Export an object to a specific URI. Only callers from the target URI may
181      * perform invocations.
182      *
183      * @param object the object to export
184      * @param uri the target URI from which connections to the object are
185      * made.
186      * @return a proxy which may be used to invoke methods on the object
187      * @throws ExportException if the object cannot be exported
188      * @throws StubNotFoundException if the proxy class cannot be found
189      */
190     Proxy exportObjectTo(Object JavaDoc object, String JavaDoc uri)
191             throws ExportException JavaDoc, StubNotFoundException JavaDoc;
192
193     /**
194      * Export an object to a specific URI. Only callers from the target URI may
195      * perform invocations.
196      *
197      * @param object the object to export
198      * @param uri the target URI from which connections to the object
199      * are made.
200      * @param principal the security principal. May be <code>null</code>
201      * @param credentials the security credentials. May be <code>null</code>
202      * @return a proxy which may be used to invoke methods on the object
203      * @throws ExportException if the object cannot be exported
204      * @throws StubNotFoundException if the proxy class cannot be found
205      */
206     Proxy exportObjectTo(Object JavaDoc object, String JavaDoc uri, String JavaDoc principal,
207                          String JavaDoc credentials)
208             throws ExportException JavaDoc, StubNotFoundException JavaDoc;
209
210     /**
211      * Unexport an object.
212      *
213      * @param object the object to export
214      * @throws NoSuchObjectException if the object isn't exported
215      */
216     void unexportObject(Object JavaDoc object) throws NoSuchObjectException JavaDoc;
217
218     /**
219      * Returns the current caller.
220      *
221      * @return the current caller, or <code>null</code> if no call is in
222      * progress
223      * @throws RemoteException for any error
224      */
225     Caller getCaller() throws RemoteException JavaDoc;
226
227     /**
228      * Register a caller event listener.
229      *
230      * @param uri the remote URI to listen on
231      * @param listener the listener to notify
232      * @throws RemoteException for any error
233      */
234     void addCallerListener(String JavaDoc uri, CallerListener listener)
235             throws RemoteException JavaDoc;
236
237     /**
238      * Deregister a caller event listener.
239      *
240      * @param uri the remote URI the listener is listening for events on
241      * @param listener the listener to remove
242      * @throws RemoteException for any error
243      */
244     void removeCallerListener(String JavaDoc uri, CallerListener listener)
245             throws RemoteException JavaDoc;
246
247     /**
248      * Shuts down the ORB.
249      *
250      * @throws RemoteException for any error
251      */
252     void shutdown() throws RemoteException JavaDoc;
253
254 }
255
Popular Tags