|
Java Platform 1.2 Beta 4 |
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
org.omg.CosNaming
for an overview of the package and for documentation for the
auxiliary classes generated to facilitate the mapping from OMG IDL
to the
JavaTM
programming language. The interface NamingContext
uses many of these auxiliary classes as parameters to its methods.
A naming context is an object that contains a set of name bindings (associations of names with object references) in which each name is unique. An object reference can have more than one name bound to it as long as each name is unique within its naming context, and an object reference can have a binding in more than one naming context. There is no requirement that an object reference be named, but when it is named, it is always done with reference to a naming context.
An initial naming context is obtained by using the ORB object's
resolve_initial_references method and then
by narrowing the type of the resulting object reference to the
type NamingContext.
org.omg.CORBA.Object objRef =
orb.resolve_initial_references("NameService");
org.omg.CosNaming.NamingContext initialnc =
org.omg.CosNaming.NamingContextHelper.narrow(objRef);
Using this initial naming context, a NamingContext
object can be created using two NamingContext methods:
new_context
NamingContext cxt = initialnc.new_context();The variable
cxt represents a new NamingContext
object that is not bound to any name. It is implemented by the same
naming server that implemented initialnc.
bind_new_context
In the code fragment below, the constructor for a
NameComponent object takes two arguments.
The first is a string for the field id, and
the second is a string for the field kind,
which may be the empty string, as shown here.
See the comments for the package CosNaming
for more information.
NameComponent comp1 = new NameComponent("apps", "");
NameComponent comp2 = new NameComponent("Hello", "");
NameComponent [] name = {comp1, comp2};
NamingContext cxt2 = initialnc.bind_new_context(name);
The variable cxt2 represents a new
NamingContext
object that is bound to name, an array of
NameComponent objects.
It is implemented by the same naming server that implemented
the naming context with name {comp1}.
Note that any NamingContext object may be
used to invoke the methods new_context and
bind_new_context, not just the initial
naming context, as shown in the example.
Because a naming context is an object, it can be bound to a name
in a naming context just like any other object. The
methods bind_context and rebind_context
are designed specifically for binding or rebinding naming contexts.
The methods bind and rebind,
which are designed for binding names with objects other than
naming contexts, can also be used to bind a name to a
naming context. However, a naming
context so bound will be treated like an object rather than a
naming context. For example, it will not be included in name
resolution when a compound name is passed to the method
resolve.
After an object has been bound to a name, it can be found
with the method resolve.
Because a naming context can contain other naming contexts, it is similar to a directory. A compound name contains a sequence of one or more naming contexts with the last component denoting the object, similar to the way a pathname contains one or more directories with the last name being the file name.
The NamingContext interface provides methods for
To get a list of name/object bindings in a naming context,
you use the method list.
The exceptions thrown by NamingContext methods are
contained in the package org.omg.CosNaming.NamingContextPackage.
These exceptions are summarized here:
NotFoundReason why -- there are three possible
values:
missing_node
not_context
not_object
NameComponent [] rest_of_name
NamingContext ctx -- using this naming
context, the client may be able to continue the operation
NameComponent [] rest_of_name
InvalidName -- thrown if the given name is
invalid. A name is invalid if it has a length of 0 or if
the id part of the name component has a length of 0.
AlreadyBound -- thrown if the given name
is already bound to
an object in this naming context. Only one object can be bound to a
particular name in a naming context.
| Method Summary | |
| void | bind_context(NameComponent[] n,
NamingContext nc)
Creates a binding of the given name with the given naming context. |
| NamingContext | bind_new_context(NameComponent[] n)
Creates a new naming context and binds it to the name supplied as an argument. |
| void | bind(NameComponent[] n,
Object obj)
Creates a binding of a name and an object relative to this naming context. |
| void | destroy()
Deletes this naming context if it contains no bindings. |
| void | list(int how_many,
BindingListHolder bl,
BindingIteratorHolder bi)
Allows a client to iterate through a set of name/object bindings in this naming context. |
| NamingContext | new_context()
Creates a new naming context implemented by the same naming server as the context on which the operation was invoked. |
| void | rebind_context(NameComponent[] n,
NamingContext nc)
Unbinds the given name from an object and rebinds it to the given naming context. |
| void | rebind(NameComponent[] n,
Object obj)
Unbinds the given name from an object and rebinds it to the given object. |
| Object | resolve(NameComponent[] n)
Retrieves the object reference bound to the given name. |
| void | unbind(NameComponent[] n)
Removes the given name binding. |
| Methods inherited from interface org.omg.CORBA.Object | |
| _create_request , _create_request , _duplicate , _get_domain_managers , _get_implementation , _get_interface , _get_policy , _hash , _is_a , _is_equivalent , _non_existent , _release , _request , _set_policy_override | |
| Method Detail |
public void bind(NameComponent[] n,
Object obj)
throws NotFound,
CannotProceed,
InvalidName,
AlreadyBound
n
- Name, which is an array of one or more
NameComponent objects, to be bound to the given object
obj
- Object to bind with the given name
public void bind_context(NameComponent[] n,
NamingContext nc)
throws NotFound,
CannotProceed,
InvalidName,
AlreadyBound
n
- Name to be bound to the NamingContext object
nc
- NamingContext a naming context object to bind
with the given name
public void rebind(NameComponent[] n,
Object obj)
throws NotFound,
CannotProceed,
InvalidName
rebind
simply binds the given name to the given object.
If the given name is a compound name and any intermediate
naming contexts are missing, this method
throws the exception NotFound.
Naming contexts that are bound using this method do not participate in name resolution when compound names are passed to be resolved.
n
- Name of an object
public void rebind_context(NameComponent[] n,
NamingContext nc)
throws NotFound,
CannotProceed,
InvalidName
rebind_context
simply binds the given name to the given naming context.
If the given name has any intermediate
naming contexts missing, this method
throws the exception NotFound.
Naming contexts that are bound using this method participate in name resolution when compound names are passed to be resolved.
n
- Name of an object
nc
- NamingContext object to bind with the given name
public Object resolve(NameComponent[] n)
throws NotFound,
CannotProceed,
InvalidName
NameComponent object (id
and kind) must match. For example,
the following code fragment, in which ctx
is a naming context and obj is an object reference,
will fail and throw the exception NOT_FOUND:
NameComponent nc1 = {"portfolio", "source_code"};
NameComponent nc2 = {"portfolio", ""};
NameComponent [] name1 = {nc1};
NameComponent [] name2 = {nc2};
ctx.bind(name1, obj);
ctx.resolve(name2);
Also, for there to be a match, all the components of a
compound name must match. If any intermediate naming contexts
are missing, the exception NOT_FOUND will be thrown.
The naming service does not return the type of the object; therefore, clients are responsible for "narrowing" (casting) the object to the appropriate type. That is, clients typically cast the returned object from Object to a more specific type using the narrow method of the type's helper class.
n
- Name of the object to be returned
public void unbind(NameComponent[] n)
throws NotFound,
CannotProceed,
InvalidName
n
- Name of the object to unbind
public void list(int how_many,
BindingListHolder bl,
BindingIteratorHolder bi)
Assigns up to the requested number of name/object bindings from this naming context to the value field of the given BindingListHolder object. If the given number is equal to or larger than the number of bindings, the entire list of bindings is assigned. If this naming context contains more bindings than requested, the method list assigns a new BindingIterator to the value field of the given BindingIteratorHolder object; otherwise, it assigns null to this field.
how_many
- the maximum number of bindings
bl
- the object to which the list of name/object bindings
will be assigned
bi
- the object to which either null or a
BindingIterator object will be assignedpublic NamingContext new_context()
public NamingContext bind_new_context(NameComponent[] n)
throws NotFound,
AlreadyBound,
CannotProceed,
InvalidName
n
- Name to be bound to the new naming context
public void destroy()
throws NotEmpty
|
Java Platform 1.2 Beta 4 |
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||