(* ---------------------------------------------------------------------- *)
(* Common Object Service 
                                                                          *)
(* ---------------------------------------------------------------------- *)
(* ICosNaming - Interface Module for the Common Object Service
                "Naming Service" 

	Purpose:
		  Provide a way to locate a service (object) given
		  a name and a type.
		
	Notes:
		  Names are strings and unique to a Naming Context.

		  Naming Contexts can contain other Naming Contexts.

		  * Most of this is defined by OMG in the
		    Common Object Services Volume 1 specification.

		  Differences:
	            The ANY type is not available in ILU so SBH (string
		    binding handles) were used instead.

		    
                                                                          *)
(* ---------------------------------------------------------------------- *)

INTERFACE ICosNaming
	IMPORTS
		ICosLifeCycle
	END;

TYPE TString = OPTIONAL ilu.CString;
TYPE TObjectSBH = OPTIONAL ilu.CString;

(* ---------------------------------------------------------------------- *)
(* A few suggested kinds for Names  *)
(* ---------------------------------------------------------------------- *)

CONSTANT kObjectKind : TString = "Object";
CONSTANT kNamingContextKind : TString = "Naming Context";
CONSTANT kModuleInterfaceKind : TString = "Module Interface";
CONSTANT kObjectInterfaceKind : TString = "Object Interface";
CONSTANT kObjectImplementationKind : TString = "Object Implementation";

(* ---------------------------------------------------------------------- *)
(* Names  *)
(* ---------------------------------------------------------------------- *)

TYPE TNameComponent = RECORD 
	aId : TString,   (* identifier *)
	aKind : TString  (* the type *)
END;

TYPE TName = SEQUENCE OF TNameComponent;

(* ---------------------------------------------------------------------- *)
(* Name Binding Types *)
(* --Notes:  *)
(*      These structures are only used with the List() method for *)
(*      dumping the contents of the database.                     *)
(* ---------------------------------------------------------------------- *)
TYPE EBindingType = ENUMERATION
	kObject,
	kContext
END;

TYPE TBinding = RECORD 
	aName : TName,        
	aType : EBindingType
END;

TYPE TBindingList = SEQUENCE OF TBinding;

(* ---------------------------------------------------------------------- *)
(* Forward declaration for CNamingContext. *)
TYPE CPNamingContext = CNamingContext;

(* ---------------------------------------------------------------------- *)
(* Exception Definitions *)
(* ---------------------------------------------------------------------- *)

TYPE ENotFoundReason = ENUMERATION
	kMissingNode,  (* cannot find binding. *)
	kNotContext,   (* found object, expecting context *)
	kNotObject     (* found context, expecting context *)
END;

TYPE TNotFoundReason = RECORD
	aReason : ENotFoundReason,  (* why? *)
	aContext : CPNamingContext, (* where? *)
	aRestOfName : TName         (* what? *)
END;


TYPE TCannotProceed = RECORD
	aContext : CPNamingContext,  (* where? *)
	aRestOfName : TName          (* what? *)
END;


EXCEPTION NotFound : TNotFoundReason "Name not found, returning reason.";
EXCEPTION CannotProceed : TCannotProceed "Cannot proceed, returning reason.";

EXCEPTION InvalidName "Invalid Name";
EXCEPTION AlreadyBound "Name Already Bound";
EXCEPTION NotEmpty "Not Empty";

(* ---------------------------------------------------------------------- *)
(* CNamingContext *)
(* ---------------------------------------------------------------------- *)


TYPE CNamingContext = OBJECT
	SUPERTYPES
		ICosLifeCycle.CLifeCycle
		(* methods: Ping and Remove *)
	END
	METHODS
		Bind(pName : TName, pObject : TObjectSBH)
		RAISES NotFound, CannotProceed, InvalidName, AlreadyBound END,
		(* Creates a binding of a name and an object in the naming 
		   context.  *)

		Rebind(pName : TName, pObject : TObjectSBH)
		RAISES NotFound, CannotProceed, InvalidName END,
		(* Creates a binding of a name and an object in the naming 
		   context even if the name is already bound in the context. *)
		
		BindContext(pName : TName, pNameContext : CNamingContext)
		RAISES NotFound, CannotProceed, InvalidName, AlreadyBound END,
		(* Names an object that is a naming context. *)

		RebindContext(pName : TName, pNameContext : CNamingContext)
		RAISES NotFound, CannotProceed, InvalidName END,
		(* Created a binding of a name and a naming context in the
		   naming context even if the name is already bound in the
		   context. *)

		Resolve(pName : TName) : TObjectSBH
		RAISES NotFound, CannotProceed, InvalidName END,
		(* Retrieves an object bound to a name in a given context.
		   The given name must exactly match the bound name. *)

		ResolveContext(pName : TName) : CNamingContext
		RAISES NotFound, CannotProceed, InvalidName END,
		(* Retrieves a naming context bound to a name in a given 
		   context. The given name must exactly match the bound name.*)

		UnBind(pName : TName, pObject : TObjectSBH)
		RAISES NotFound, CannotProceed, InvalidName, NotEmpty END,
		(* Removes the name from the naming context. The given name
		   must exactly match the bound name. *)		

		NewContext() : CNamingContext,
		(* Creates a new naming context and returns it.  It is not
		   currently bound to any context. *)

		BindNewContext(pName : TName) 
		RAISES NotFound, CannotProceed, InvalidName, AlreadyBound END,
		(* Creates a new naming context and returns it.  It binds
		   it to the given name in the current naming context. *)

		List(pHowMany : CARDINAL) : TBindingList
		(* returns the first 'pHowMany' name bindings in the current
		   context. *)
	END;


	
(* ---------------------------------------------------------------------- *)
(* Symbol prefixing: I - Interface Module
		     C - Class Interface
		     T - Non-class Type
		     E - Enumeration Type
		     k - constant
		     p - parameter to a method
		     a - variable
                                                                          *)
(* ---------------------------------------------------------------------- *)