KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > objectweb > jonathan > apis > binding > Identifier


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.binding;
29
30 import org.objectweb.jonathan.apis.kernel.JonathanException;
31 import org.objectweb.jonathan.apis.kernel.Context;
32 import org.objectweb.jonathan.apis.presentation.Marshaller;
33
34 /**
35  * An identifier uniquely identifies an applicative object interface in a given
36  * {@link NamingContext naming context}. It is a specific kind of
37  * {@link org.objectweb.jonathan.model.name name}.
38  */
39 public interface Identifier {
40    /**
41     * Returns the naming context associated with the target identifier.
42     *
43     * An identifier is always associated the naming context that created it.
44     *
45     * @return the naming context associated with the target identifier.
46     */
47    public NamingContext getContext();
48
49    /**
50     * The bind operation returns an object giving access to the object interface
51     * referenced by the target identifier.
52     * <p>
53     * The returned object may be a direct reference to the object interface that
54     * was used to create the identifier (at export-time), or it may be a surrogate
55     * (a proxy) for that object interface.
56     * <p>
57     * If this operation is implemented, it means that the related naming context
58     * is not only a
59     * {@link org.objectweb.jonathan.model.naming_context naming context} but
60     * also a {@link org.objectweb.jonathan.model.binder binder}.
61     * <p>
62     * This operation may in particular raise two types of exceptions:
63     * <ul>
64     * <li> {@link ForwardException ForwardExceptions} that indicate that the
65     * "real" target object interface should be bound using the
66     * {@link ForwardException#reference reference}
67     * contained in the exception. Note that in this case, calling the
68     * {@link #resolve() resolve} method should return the same reference.
69     * This facility may be used to handle mobility.
70     * <li> {@link BindException BindExceptions} that indicate that an error
71     * occurred in the binding process;
72     * </ul>
73     * <p>
74     * All parameters are optional (they may be null).
75     * <ul>
76     * <li> The <tt>ref</tt> parameter
77     * is an array of identifiers, to which the target identifier should belong:
78     * Object interfaces may be identified by several identifiers, and it
79     * is useful to maintain this list of identifiers, even if only one
80     * identifier is used to actually give access to the designated object
81     * interface. This parameter has been added as a convenience to achieve
82     * this, but it may not be meaningfull in all cases.
83     * <li> The <tt>hints</tt> parameter contains information that may be required
84     * by naming contexts to build the returned object. Here again, it may not
85     * be meaningfull in all cases.
86     * </ul>
87     *
88     * @param ref a set of identifiers of the seeked object interface;
89     * @param hints a context containing extra information that may be useful;
90     * @return a reference to the seeked interface.
91     * @exception ForwardException if the target has moved;
92     * @exception BindException if an error occurs in the binding process;
93     * @exception JonathanException if something else goes wrong.
94     * @see org.objectweb.jonathan.model.binder#bind(org.objectweb.jonathan.model.name)
95     */
96    public Object JavaDoc bind(Identifier[] ref,Context hints)
97       throws ForwardException, BindException, JonathanException;
98
99    
100    /**
101     * Unexporting an identifier means that the target identifier no longer
102     * designates the object interface it was created for (by some <tt>export</tt>
103     * method). An identifier must no longer be used after it has been "unexported".
104     */
105    public void unexport();
106    
107    /**
108     * Tests the validity of the target identifier.
109     * A <tt>false</tt> return means that a call to either
110     * {@link #bind(Identifier[],Context) bind} or {@link #resolve() resolve} will
111     * fail. If so, the target identifier must no longer be used.
112     *
113     * @return false if calls to either {@link #bind(Identifier[],Context) bind} or
114     * {@link #resolve() resolve} certainly fail.
115     */
116    public boolean isValid();
117    
118    /**
119     * Returns the next name in the referencing chain.
120     * <p>
121     * If the naming context that has built the target identifier is an intermediate
122     * naming context, this method should return the next "name" in the referencing
123     * chain, or null if no such name can be found or created.
124     * <p>
125     * Such a name may be of type {@link Identifier Identifier},
126     * {@link Reference Reference}, or of any other type, provided that it really
127     * designates the right interface, and that its type is clear from the context.
128     *
129     * @return the next name in the referencing chain.
130     * @see org.objectweb.jonathan.model.naming_context#resolve(org.objectweb.jonathan.model.name)
131     */
132    public Object JavaDoc resolve();
133
134    /**
135     * Encodes the target identifier in an array of bytes.
136     * <p>
137     * Since identifiers are likely to be transmitted on the net, they may have to be
138     * encoded and decoded. The corresponding
139     * {@link NamingContext#decode(byte[],int,int) decoding} method is borne
140     * by the {@link NamingContext NamingContext} interface.
141     *
142     * @return an array of bytes encoding the target identifier.
143     * @exception JonathanException if something goes wrong.
144     */
145    public byte[] encode() throws JonathanException;
146
147
148    /**
149     * Encodes the target identifier in a marshaller.
150     *
151     * @param m the marshaller to be used for encoding.
152     * @exception JonathanException if something goes wrong.
153     */
154    public void encode(Marshaller m) throws JonathanException;
155
156 }
157
158
159
Popular Tags