Namespace Service User's Guide

Version 1.0.3

Last updated: August 26, 2011


Table of Contents

Overview

Installation and Configuration

Request Syntax

  • CREATE
  • MODIFY
  • DELETE
  • LIST
  • QUERY
  • SET
  • GET
  • VERSION
  • HELP
  • Error Code Reference

    Service Logging

    Service Data Storage

  • Namespaces DTD
  • Namespaces XML File
  • Backup XML Files

  • Overview

    The Namespace service is an external STAF service written in Java. The purpose of the Namespace service is to provide a namespace hierarchy for storing and retrieving a persistent repository of variables. This service allows the creation of namespaces and allows you to set key/value pairs (e.g. variables) in a namespace. Namespaces may inherit variables from a parent namespace, thus creating a namespace hierarchy. Variable look-ups will be done within a namespace scope. If a variable cannot be found in the given namespace, resolution will be attempted in the parent namespace, and so on up the hierarchy.

    Unlike the VAR service, any variables set in a namespace will persist across stops and restarts of STAF with no additional steps required by the user. This will be done by immediately updating an XML file when any updates are made to namespaces.

    Here's an example of a namespace hierarchy:

    Namespace Hierarchy


    Installation and Configuration

    1. Install Java 1.3 or later.

    2. Install STAF 3.0.0 or later by following the installation instructions in the STAF documentation.

    3. Install the Namedpace service:

      Download the NamespaceV103.zip/tar file from Get STAF Services into a local directory (e.g. C:/STAF/services or /usr/local/staf/services) and extract it.

    4. Configure the Namespace service:

      Add the following statement to your staf.cfg file:

      SERVICE <Service Name> LIBRARY JSTAF EXECUTE <Service Jar File Name> \
                             PARMS "[DIRECTORY <Directory>] [FILENAME <FileName>]"
      

      where:

      Examples:

      SERVICE Namespace LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/services/namespace/Namespace.jar

      SERVICE NS LIBRARY JSTAF EXECUTE C:/STAF/services/namespace/Namespace.jar \
              PARMS "DIRECTORY C:/test/namespace FILENAME NS.xml"
      

      Or, you can dynamically add the Namespace service using the SERVICE service's ADD SERVICE request.

    In most cases, the way that you would use this service is that you would designate a system as the Namespace Server. That system would have STAF installed, plus the Namespace service with the SERVICE configuration statement in the configuration file that is shown above. Assuming that the machine name for the Namespace server is server1 and the registered service name is Namespace, an example of the command line interface to create a namespace is:

       STAF server1 Namespace CREATE NAMESPACE AIS DESCRIPTION "Global AIS Namespace"


    Request Syntax

    The Namespace service provides the following requests:

    CREATE

    The CREATE command creates a new namespace in which variables may be created. The namespace may optionally inherit variables from another, already existing, namespace. If the namespace has no parent it will inherit no variables.

    The only reserved name for a namespace is the string NONE, case insensitive. This string will be used to represent a root namespace -- a namespace that does not have a parent.

    Syntax

    CREATE NAMESPACE <Name> DESCRIPTION <Description> [PARENT <Name>]

    NAMESPACE specifies the name of the namespace to create. This can be any string (except for NONE, case insensitive, which is reserved). This option will resolve variables.

    DESCRIPTION specifies a textual description of the new namespace.

    PARENT specifies the name of the parent namespace that this namespace should inherit variables from. The parent namespace must exist. If the PARENT option is not specified, the new namespace will have no parent and will not inherit any variables. This can also be achieved by specifying NONE (case-insensitive). This option is optional. This option will resolve variables.

    Security

    This command requires trust level 3.

    Results

    Upon successful return, the result buffer will be empty.

    Examples:

    MODIFY

    The MODIFY command may be used to modify the parent and/or description of an existing namespace.

    Syntax

    MODIFY NAMESPACE <Name> [DESCRIPTION <Description>] [PARENT <Name>]

    NAMESPACE specifies the name (case-insensitive) of the namespace to be modified. This option will resolve variables.

    DESCRIPTION specifies the new description for this namespace.

    PARENT specifies the name (case-insensitive) of the new parent for this namespace. This option will resolve variables. Be aware that any children of this namespace will keep this namespace as their parent and will move to the new hierarchy location as well. To specify that the namespace should be modified to have no parent (a root namespace), then specify NONE (case-insensitive).

    At least one of the DESCRIPTION or PARENT options must be specified, but both may specified as well.

    Security

    This command requires trust level 3.

    Results

    Upon successful return, the result buffer will be empty.

    Examples

    DELETE

    The DELETE command may be used to delete one or more variables from a namespace or to delete a namespace.

    Syntax

    DELETE NAMESPACE <Name> <VAR <Key>... | CONFIRM>

    NAMESPACE specifies the name (case-insensitive) of a namespace. This option will resolve variables.

    VAR specifies the key (case-insensitiveI) of a variable to delete from the namespace. This option may appear more than one time. This option will resolve variables.

    CONFIRM indicates that you want to delete the namespace and any variables directly contained within it. If the namespace has any child namespaces, their parents will be changed to be the parent of the deleted namespace.

    You cannot specify both the VAR and CONFIRM options.

    Security

    This command requires trust level 4 if deleting a namespace or trust level 3 if deleting a variable from a namespace.

    Results

    Upon successful return, the result buffer will be empty.

    Examples

    LIST

    The LIST command may be used to list all namespaces or variables defined within a namespace, or the settings for the service, depending on the option(s) specified.

    Syntax

    LIST [NAMESPACES | <NAMESPACE <Name> [ONLY]> | SETTINGS] 
    

    NAMESPACES specifies to list all namespaces. This is the default.

    NAMESPACE specifies the name (case-insensitive) of a namespace for which its variables will be listed. This option will resolve variables.

    ONLY specifies to list only the variables defined directly in the specified namespace. None of the variables from any parents of this namespace will be listed. If the ONLY option is not specified, all variables from the given namespace will be listed as well as any variables from parent namespaces which were not overridden n this namespace.

    SETTINGS specifies to list the settings for the service.

    If neither the NAMESPACE nor NAMESPACES nor SETTINGS option is specified, a list of the namespaces will be returned.

    Security

    This command requires trust level 2.

    Results

    Upon successful return,

    Examples

    For the following examples, assume that the namespaces are defined as shown in the example XML file in the Namespaces XML File section.

    QUERY

    The QUERY command may be used to query information about a single namespace or to view the namespace hierarchy from the given namespace down the hierarchy through all leaf namespaces.

    Syntax

    QUERY NAMESPACE <Namespace> [TREE]

    NAMESPACE specifies the name (case-insensitive) of the namespace to query. This option will resolve variables.

    TREE indicates to return the tree hierarchy view from the given namespace down through all child leaf namespaces.

    Security

    This command requires trust level 2.

    Results

    Upon successful return:

    Examples

    For the following examples, assume that the namespaces are defined as shown in the example XML file in the Namespaces XML File section.

    SET

    The SET command creates or modifies one or more variables within a namespace.

    Syntax

    SET VAR <Key=Value> [VAR <Key=Value>] NAMESPACE <Name>

    VAR specifies the key and value of the variable to set, separated by "=". This parameter may appear 1 or more times.

    NAMESPACE specifies the name (case-insensitiveI) of the namespace in which to create the variable(s). This option will resolve variables.

    Security

    This command requires trust level 3.

    Results

    On a successful return, the result buffer will be empty.

    Examples

    GET

    The GET command gets the value of a particular variable within a namespace. If the variable does not exist in the specified namespace, the parent namespace will be checked and so on up the hierarchy. The value for the first instance of the variable found will be returned.

    Syntax

    GET VAR <Key> NAMESPACE <Name>

    VAR specifies the key (case-insensitive) of the variable that you want to get the value of. This option will resolve variables.

    NAMESPACE specifies the name (case-insensitive) of the namespace in which to begin looking for the variable. This option will resolve variables.

    Security

    This command requires trust level 2.

    Results

    On a successful return, the result buffer will contain the value for the first instance of the variable found.

    Examples

    For the following examples, assume that the namespaces are defined as shown in the example XML file in the Namespaces XML File section.

    VERSION

    VERSION displays the Namespace Service version.

    Syntax

    VERSION

    Security

    This request requires at least trust level 1.

    Results

    The result is the version number of the Namespace service.

    Examples

    HELP

    HELP displays the request options and how to use them.

    Syntax

    HELP

    Security

    This request requires at least trust level 1.

    Results

    The result buffer contains the Help messages for the request options for the Namespace service.

    Examples


    Error Code Reference

    In addition to the common STAF return codes, the following service return codes are defined for the Namespace service:
     
    Error Code Meaning  Comment 
    4001 Data storage error An error occurred saving namespaces data to persistent storage. Additional information about the error is put into the STAF Result.


    Service Logging

    The Namespace service maintains a global log where it writes an entry when:

    The logname for the Namespace service is the name under which the service is registered.

    Here is an example of what a Namespace service log (with the Namespace service's registered name begin NS) could look like shown via a request from the command line in the table format:

    C:\>STAF local LOG QUERY GLOBAL LOGNAME NS
    Response
    --------
    20051016-16:43:24 Start Initialized the NS service
    20051016-16:44:47 Info  [local://local STAX/Job/1 27] CREATE NAMESPACE WebSpher
                            eSVT DESCRIPTION WebSphere SVT Namespace PARENT WAS
    20051016-16:44:47 Info  [local://local STAX/Job/1 27] SET NAMESPACE WebSphereSV
                            T VAR WASSVTVar1=WASSVTValue1 VAR WASSVTVar2=WASSVTValu
                            e2 VAR WASVar2=OverrideWASValue2 VAR GlobalVar2=Overrid
                            eGlobalValue2
    20051016-16:44:47 Info  [local://local STAX/Job/1 27] CREATE NAMESPACE DB2 DESC
                            RIPTION Global DB2 Namespace PARENT AIS
    20051016-16:44:48 Info  [local://local STAX/Job/1 27] SET NAMESPACE DB2 VAR DB2
                            Var1=DB2Value1 VAR DB2Var2=DB2Value2
    20051016-16:44:52 Info  [local://local STAX/Job/1 27] DELETE NAMESPACE WEBSpher
                            eSVT CONFIRM
    20051016-16:44:53 Info  [local://local STAX/Job/1 27] DELETE NAMESPACE DB2 CONF
                            IRM
    20051016-16:46:42 Stop  Terminating the NS service
    


    Service Data Storage

    Unlike the VAR service, any variables set in a namespace will persist across stops and restarts of STAF with no additional steps required by the user. This will be done by immediately updating an XML file when any updates are made to namespaces.

    Namespaces DTD

    The Namespaces Document Type Definition (DTD) is defined as follows and will be used to validate the Namespaces XML file. Parent-child relationships are represented by nested <namespace> elements.
    <!--
       STAF Namespaces Document Type Definition (DTD)
    
       This DTD module is identified by the SYSTEM identifier:
    
         SYSTEM 'resources/Namespaces.dtd'
    
    -->
    
    <!ELEMENT namespaces     (namespace)*>
    
    <!ELEMENT namespace      (var*, namespace*)>
    <!ATTLIST namespace
              name           CDATA    #REQUIRED
              description    CDATA    #REQUIRED
    >
    
    <!ELEMENT var            (#PCDATA)>
    <!ATTLIST var
              key            CDATA    #REQUIRED
              value          CDATA    #REQUIRED
    >
    

    Namespaces XML File

    The Namespace service stores namespaces and their variables in an XML file. By default the file is named Namespaces.xml and is located in directory {STAF/DataDir}/service/<Service Name (lower-case)>. To override the storage location, you can specify the DIRECTORY and/or FILENAME options in the PARMS value when registering the Namespace service. See the Installation and Configuration section for more information on setting these parameters.

    The Namespace service immediately updates this XML file at the end of each successful CREATE, MODIFY, DELETE, or SET request.

    For example, on Windows, the Namespaces xml file will be stored in C:\STAF\data\STAF\service\ns\Namespacees.xml if the Namespace service is registered as NS with no parameters and STAF is installed at C:\STAF using the default STAF instance name of STAF.

    Here's an example of a Namespaces xml file:

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE namespaces SYSTEM "resources/Namespaces.dtd">
    <namespaces>
      <namespace description="Global AIS Namespace" name="AIS">
        <var key="GlobalVar1" value="GlobalValue1"/>
        <var key="GlobalVar2" value="GlobalValue2"/>
        <var key="GlobalVar3" value="GlobalValue3"/>
        <namespace description="Global DB2 Namespace" name="DB2">
          <var key="DB2Var1" value="DB2Value1"/>
          <var key="DB2Var2" value="DB2Value2"/>
        </namespace>
        <namespace description="Global WebSphere Namespace" name="WAS">
          <var key="WASVar1" value="WASValue1"/>
          <var key="WASVar2" value="WASValue2"/>
          <namespace description="WebSphere SVT Namespace" name="WebSphereSVT">
            <var key="GlobalVar2" value="OverrideGlobalValue2"/>
            <var key="WASSVTVar1" value="WASSVTValue1"/>
            <var key="WASSVTVar2" value="WASSVTValue2"/>
            <var key="WASVar2" value="OverrideWASValue2"/>
          </namespace>
        </namespace>
      </namespace>
      <namespace description="User Independent Namespace" name="MyIndependentNS">
        <var key="MyVar1" value="MyValue1"/>
        <var key="MyVar2" value="MyValue2"/>
      </namespace>
    </namespaces>

    Backup XML Files

    For backup purposes, the Namespace service makes a temporary copy of the Namespaces xml file at the following times:

    These files are temporary because they are stored in STAF's temporary directory ({STAF/DataDir}/tmp). STAF's temporary directory and all of its contents are deleted whenever STAF is restarted.

    The directory where these temporary files are stored is:

      {STAF/DataDir}/tmp/service/<Service Name (lower-case)>.

    For example, on Windows, this directory could be C:\STAF\data\STAF\tmp\service\ns.

    The format of the names of the copied Namespace xml files will be:

     <Namespace File Name>.<Phase>.<Current Time (milli-seconds)>

    So, for example, the temporary directory for the Namespace service could contain files such as:

    Namespaces.xml.init.1129499304537
    Namespaces.xml.delete.1129499341040
    Namespaces.xml.delete.1129499341200
    Namespaces.xml.term.1129499418842
    

    Also, a backup of the Namespaces xml file named <Namespace FileName>.backup is created immediately before the Namespace service updates the Namespaces.xml file during a CREATE, MODIFY, DELETE, or SET request. This backup file is located in the namespace directory along with the Namespaces xml file.