org.omg.CosNaming.nameservice.idl Maven / Gradle / Ivy
Show all versions of openjdk-orb Show documentation
/*
* Copyright (c) 1996, 2010, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
// name.idl - Naming service interface
#pragma prefix "omg.org"
/**
* The CORBA COS Naming Service provides the ability to bind a name
* to an object relative to a naming context. A naming context is an
* object that contains a set of name bindings in which each name is unique.
* To resolve a name is to determine the object associated with the name in
* a given context.
*
* See http://www.omg.org/technology/documents/formal/naming_service.htm
* for the complete CORBA
* COS Naming Specification.
*/
module CosNaming
{
typedef string Istring;
/**
* Many of the operations defined on a naming context take names as
* parameters. Names have structure. A name is an ordered sequence of
* components.
*
* A name with a single component is called a simple name; a name with
* multiple components is called a compound name. Each component except
* the last is used to name a context; the last component denotes the
* bound object.
*
* A name component consists of two attributes: the identifier
* attribute and the kind attribute. Both the identifier attribute and the
* kind attribute are represented as IDL strings. The kind attribute adds
* descriptive power to names in a syntax-independent way. Examples of the
* value of the kind attribute include c_source, object_code, executable,
* postscript, or " ".
*/
struct NameComponent
{
Istring id;
Istring kind;
};
/**
* A name is a sequence of name components.
*/
typedef sequence Name;
/**
* Specifies whether the given binding is for a object (that is not a
* naming context) or for a naming context.
*/
enum BindingType
{
nobject, // name is bound to an object
ncontext // name is bound to a naming context
};
/**
* A name-to-object association is called a Binding.
*/
struct Binding
{
Name binding_name; // name
BindingType binding_type; // whether name is bound to an object
// or a naming context
};
/**
* List of Bindings.
*/
typedef sequence BindingList;
/**
* The BindingIterator interface allows a client to iterate through
* the bindings using the next_one or next_n operations.
*
* The bindings iterator is obtained by using the list
* method on the NamingContext.
* @see org.omg.CosNaming.NamingContext#list
*/
interface BindingIterator
{
/**
* This operation returns the next binding. If there are no more
* bindings, false is returned.
*
* @param b the returned binding
*/
boolean next_one(out Binding b);
/**
* This operation returns at most the requested number of bindings.
*
* @param how_many the maximum number of bindings tro return
*
* @param bl the returned bindings
*/
boolean next_n(in unsigned long how_many,
out BindingList bl);
// Destroy binding iterator
/**
* This operation destroys the iterator.
*/
void destroy();
};
/**
* A naming context is an object that contains a set of name bindings in
* which each name is unique. Different names can be bound to an object
* in the same or different contexts at the same time.
*
* See
* CORBA COS
* Naming Specification.
*/
interface NamingContext
{
// Declare exceptions
/**
* Indicates the reason for not able to resolve.
*/
enum NotFoundReason
{
missing_node,
not_context,
not_object
};
/**
* Indicates the name does not identify a binding.
*/
exception NotFound
{
NotFoundReason why;
Name rest_of_name;
};
/**
* Indicates that the implementation has given up for some reason.
* The client, however, may be able to continue the operation at the
* returned naming context.
*/
exception CannotProceed
{
NamingContext cxt;
Name rest_of_name;
};
/**
* Indicates the name is invalid.
*/
exception InvalidName
{};
/**
* Indicates an object is already bound to the specified name. Only
* one object can be bound to a particular name in a context.
*/
exception AlreadyBound
{};
/**
* Indicates that the Naming Context contains bindings.
*/
exception NotEmpty
{};
/**
* Creates a binding of a name and an object in the naming context.
* Naming contexts that are bound using bind do not participate in name
* resolution when compound names are passed to be resolved.
*
* @param n Name of the object
*
* @param obj The Object to bind with the given name
*
* @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates
* the name does not identify a binding.
*
* @exception org.omg.CosNaming.NamingContextPackage.CannotProceed
* Indicates that the implementation has given up for some reason.
* The client, however, may be able to continue the operation
* at the returned naming context.
*
* @exception org.omg.CosNaming.NamingContextPackage.InvalidName
* Indicates that the name is invalid.
*
* @exception org.omg.CosNaming.NamingContextPackage.AlreadyBound
* Indicates an object is already bound to the specified name.
*/
void bind(in Name n,
in Object obj)
raises(NotFound,
CannotProceed,
InvalidName,
AlreadyBound);
/**
* Names an object that is a naming context. Naming contexts that
* are bound using bind_context() participate in name resolution
* when compound names are passed to be resolved.
*
* @param n Name of the object
*
* @param nc NamingContect object to bind with the given name
*
* @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.
*
* @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
* given up for some reason. The client, however, may be able to
* continue the operation at the returned naming context.
*
* @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid.
*
* @exception org.omg.CosNaming.NamingContextPackage.AlreadyBound Indicates an object is already
* bound to the specified name.
*/
void bind_context(in Name n,
in NamingContext nc)
raises(NotFound,
CannotProceed,
InvalidName,
AlreadyBound);
/**
* Creates a binding of a name and an object in the naming context
* even if the name is already bound in the context. Naming contexts
* that are bound using rebind do not participate in name resolution
* when compound names are passed to be resolved.
*
* @param n Name of the object
*
* @param obj The Object to rebind with the given name
*
* @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.
*
* @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
* given up for some reason. The client, however, may be able to
* continue the operation at the returned naming context.
*
* @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid.
*/
void rebind(in Name n,
in Object obj)
raises(NotFound,
CannotProceed,
InvalidName);
/**
* Creates a binding of a name and a naming context in the naming
* context even if the name is already bound in the context. Naming
* contexts that are bound using rebind_context() participate in name
* resolution when compound names are passed to be resolved.
*
* @param n Name of the object
*
* @param nc NamingContect object to rebind with the given name
*
* @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.
*
* @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
* given up for some reason. The client, however, may be able to
* continue the operation at the returned naming context.
*
* @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid.
*/
void rebind_context(in Name n,
in NamingContext nc)
raises(NotFound,
CannotProceed,
InvalidName);
/**
* The resolve operation is the process of retrieving an object
* bound to a name in a given context. The given name must exactly
* match the bound name. The naming service does not return the type
* of the object. Clients are responsible for "narrowing" the object
* to the appropriate type. That is, clients typically cast the returned
* object from Object to a more specialized interface.
*
* @param n Name of the object
*
* @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.
*
* @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
* given up for some reason. The client, however, may be able to
* continue the operation at the returned naming context.
*
* @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid.
*/
Object resolve(in Name n)
raises(NotFound,
CannotProceed,
InvalidName);
/**
* The unbind operation removes a name binding from a context.
*
* @param n Name of the object
*
* @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.
*
* @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
* given up for some reason. The client, however, may be able to
* continue the operation at the returned naming context.
*
* @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid.
*/
void unbind(in Name n)
raises(NotFound,
CannotProceed,
InvalidName);
/**
* The list operation allows a client to iterate through a set of
* bindings in a naming context.
*
* The list operation returns at most the requested number of
* bindings in BindingList bl.
*
* - If the naming context contains additional
* bindings, the list operation returns a BindingIterator with the
* additional bindings.
*
- If the naming context does not contain additional
* bindings, the binding iterator is a nil object reference.
*
*
* @param how_many the maximum number of bindings to return
*
* @param bl the returned list of bindings
*
* @param bi the returned binding iterator
*/
void list(in unsigned long how_many,
out BindingList bl,
out BindingIterator bi);
/**
* This operation returns a naming context implemented by the same
* naming server as the context on which the operation was invoked.
* The new context is not bound to any name.
*/
NamingContext new_context();
/**
* This operation creates a new context and binds it to the name
* supplied as an argument. The newly-created context is implemented
* by the same naming server as the context in which it was bound (that
* is, the naming server that implements the context denoted by the
* name argument excluding the last component).
*
* @param n Name of the object
*
* @exception org.omg.CosNaming.NamingContextPackage.NotFound Indicates the name does not identify a binding.
*
* @exception org.omg.CosNaming.NamingContextPackage.AlreadyBound Indicates an object is already
* bound to the specified name.
*
* @exception org.omg.CosNaming.NamingContextPackage.CannotProceed Indicates that the implementation has
* given up for some reason. The client, however, may be able to
* continue the operation at the returned naming context.
*
* @exception org.omg.CosNaming.NamingContextPackage.InvalidName Indicates that the name is invalid.
*/
NamingContext bind_new_context(in Name n)
raises(NotFound,
AlreadyBound,
CannotProceed,
InvalidName);
/**
* The destroy operation deletes a naming context. If the naming
* context contains bindings, the NotEmpty exception is raised.
*
* @exception org.omg.CosNaming.NamingContextPackage.NotEmpty Indicates that the Naming Context contains bindings.
*/
void destroy()
raises(NotEmpty);
};
/**
* NamingContextExt is the extension of NamingContext
* which
* contains a set of name bindings in which each name is unique and is
* part of Interoperable Naming Service.
* Different names can be bound to an object in the same or different
* contexts at the same time. Using NamingContextExt, you can use
* URL-based names to bind and resolve.
*
* See
* CORBA COS
* Naming Specification.
*/
interface NamingContextExt: NamingContext
{
/**
* StringName is the Stringified Name, Array of Name Components
* represented as a String.
*/
typedef string StringName;
/**
* Address is the Host and Port information represented as a String.
*/
typedef string Address;
/**
* URLString is the URL address (corbaloc: or corbaname:) represented as
* a String.
*/
typedef string URLString;
/**
* This operation creates a stringified name from the array of Name
* components.
*
* @param n Name of the object
*
* @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName
* Indicates the name does not identify a binding.
*
*/
StringName to_string( in Name n ) raises (InvalidName);
/**
* This operation converts a Stringified Name into an equivalent array
* of Name Components.
*
* @param sn Stringified Name of the object
*
* @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName
* Indicates the name does not identify a binding.
*
*/
Name to_name( in StringName sn ) raises (InvalidName);
/**
* Indicates the invalid Stringified name for the object, The
* reason could be invalid syntax.
*/
exception InvalidAddress
{ };
/**
* This operation creates a URL based "iiopname://" format name
* from the Stringified Name of the object.
*
* @param addr internet based address of the host machine where Name Service is running
* @param sn Stringified Name of the object
*
* @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName
* Indicates the name does not identify a binding.
* @exception org.omg.CosNaming.NamingContextPackage.InvalidAddress
* Indicates the internet based address of the host machine is
* incorrect
*
*/
URLString to_url( in Address addr, in StringName sn )
raises( InvalidAddress, InvalidName );
/**
* This operation resolves the Stringified name into the object
* reference.
*
* @param sn Stringified Name of the object
*
* @exception org.omg.CosNaming.NamingContextPackage.NotFound
* Indicates there is no object reference for the given name.
* @exception org.omg.CosNaming.NamingContextPackage.CannotProceed
* Indicates that the given compound name is incorrect
* @exception org.omg.CosNaming.NamingContextExtPackage.InvalidName
* Indicates the name does not identify a binding.
*
*/
Object resolve_str( in StringName sn)
raises( NotFound, CannotProceed,
InvalidName);
};
};