= The Name Service =

The Name Service allows users to associate a string with a piece of arbitrary data (often a [[Handle]]).  Both cluster-wide, node-wide, and process-only data can be associated with the name.  This allows name service users to also associate shared memory pointers and local pointers to a particular name.  For example, these pointers could reference objects which represent the local instantiation of an entity.

All SAFplus API calls that accept a string name use the Name Service to resolve the string into the actual [[Handle]] or object.  Since components and services accept a strings in their "create" APIs, it is possible that the end user will never explicitly use the Name Service yet it be heavily utilized.

The name service can also be used independently of other SAFplus APIs by user applications.  In this case, its use is a cluster wide name:value dictionary.  For example, a handle to the "Active" server application could be stored under a name so that clients can discover which server is active easily.


== Implementation ==

The Name Service is a client library that is linked with every component that uses it.  It opens a cluster-wide, shared memory, non-persistent checkpoint using the name service's well-known [[Handle]].

The name service uses this checkpoint to resolve string names into objects.

== Header ==
#include <clNameApi.hxx>
== APIs ==

{{{#!highlight cpp
class NameException: public std::exception
{
  ...
};

class NameRegistrar
  {
  public:

    typedef enum {
         MODE_REDUNDANCY,
         MODE_ROUND_ROBIN,
         MODE_PREFER_LOCAL/* return a handle that points to this process (if it exists)
                             if it does not exist return a handle that points to this NODE.
                             if that does not exist, return any handle
                             So choose "closer" handles over ones that are far away
                             this mode makes communications more efficient
                          */
         MODE_NO_CHANGE,  /* This is not a mode; it tells the API to not change the existing mode (or use MODE_REDUNDANCY if creating) */

         } MappingMode;
    /* For more convenience and logical, should move mapping mode setting to set functions
       For more clearance on this parameter, see the comments of the functions
    */ 
    //void setMode(const char* name, MappingMode m);
     

    /* Associate a name with a handle and pointer and associate a handle with a pointer.
       If the name does not exist, it is created.  If it exists, it is overwritten.
       If the handle format contains a node or process designator, then this mapping will be removed when the node/process fails.

       the void* object pointer is local to this process; it does not need to be part of the checkpoint.
       
       This association is valid for all SAFplus API name lookups, and for AMF entity names.
       The mapping mode parameter is mandatory and specifies what the mapping mode is, based on it, the get functions retrieves appropriate handles
     */
    void set(const char* name, SAFplus::Handle handle, MappingMode m, void* object=NULL);
    void set(const std::string& name, SAFplus::Handle handle, MappingMode m, void* object=NULL);
    

     /* Associate a name with a handle and pointer and associate a handle with a pointer (if object != NULL).
        If the name does not exist, it is created.  If the name exists, this mapping is appended (the original mapping is not removed).
        If there are multiple associations, the first association will always be returned.
        If the handle format contains a node or process designator, then this mapping will be removed when the node/process fails.
        If the name has more than one mapping another mapping will become the default response for this name. 

        This association is valid for all SAFplus API name lookups, and for AMF entity names.
        The mapping mode parameter is mandatory and specifies what the mapping mode is, based on it, the get functions look up appropriate handle: if it's different from MappingMode::MODE_NO_CHANGE, the mapping mode that was set for this name before will be replaced with it, otherwise (omitted), the mapping mode that was set for this name before will be kept as it was (no change)
      */   
    void append(const char* name, SAFplus::Handle handle, MappingMode m, void* object=NULL);
    void append(const std::string& name, SAFplus::Handle handle, MappingMode m, void* object=NULL);    
    // Associate name with arbitrary data. A copy of the data is made.
    void set(const char* name, const void* data, int length);
    void set(const std::string& name, const void* data, int length);

    // Associate name with arbitrary data. A copy of the data is NOT made; this call transfers the reference count (ownership) to the callee.
    void set(const char* name, SAFplus::Buffer*);
    void set(const std::string& name, SAFplus::Buffer*);

    // Get a handle associated with the data
    // The SAFplus APIs use these calls to resolve names to handles or objects.
    std::pair<SAFplus::Handle&,void* object> get(const char* name) throws(NameException&);
    std::pair<SAFplus::Handle&,void* object> get(const std::string& name) throws(NameException&);

    SAFplus::Handle& get(const char* name) throws(NameException&);
    SAFplus::Handle& get(const std::string& name) throws(NameException&);
 
    // Get object based on handle
    void* get(const SAFplus::Handle&) throws(NameException&);

    
    // Get a handle associated with the data
    // The SAFplus APIs use these calls to resolve names to handles or objects.
    // Do not free the returned buffer, call Buffer.decRef();
    SAFplus::Buffer& get(const char* name) throws(NameException&);
    SAFplus::Buffer& get(const std::string& name) throws(NameException&);

    
  };

// Name is a singleton class; only one per process.
extern NameRegistrar name;

}}}