tech-invite   World Map
3GPP     Specs     Glossaries     UICC       IETF     RFCs     Groups     SIP     ABNFs       T+       Search     Home

RFC 2614

 
 
 

An API for Service Location

Part 3 of 3, p. 56 to 91
Prev RFC Part

 


prevText      Top      Up      ToC       Page 56 
5. Java Language Binding

5.1. Introduction

   The Java API is designed to model the various SLP entities in classes
   and objects.  APIs are provided for SA, UA, and service type template
   access capabilities.  The ServiceLocationManager class contains
   methods that return instances of objects implementing SA and UA
   capability.  Each of these is modeled in an interface.  The Locator
   interface provides UA capability and the Advertiser interface
   provides SA capability.  The TemplateRegistry abstract class contains
   methods that return objects for template introspection and attribute
   type checking.  The ServiceURL, ServiceType, and
   ServiceLocationAttribute classes model the basic SLP concepts.  A
   concrete subclass instance of TemplateRegistry is returned by a class
   method.

   All SLP classes and interfaces are located within a single package.
   The package name should begin with the name of the implementation and
   conclude with the suffix "slp".  Thus, the name for a hypothetical
   implementation from the University of Michigan would look like:

                             edu.umich.slp

   This follows the Java convention of prepending the top level DNS
   domain name for the organization implementing the package onto the
   organization's name and using that as the package prefix.

5.2. Exceptions and Errors

   Most parameters to API methods are required to be non-null.  The API
   description indicates if a null parameter is acceptable, or if other
   restrictions constrain a parameter.  When parameters are checked for
   validity (such as not being null) or their syntax is checked, an
   error results in the RuntimeException subclass
   IllegalArgumentException being thrown.  Clients of the API are
   reminded that IllegalArgumentException, derived from
   RuntimeException, is unchecked by the compiler.  Clients should thus
   be careful to include try/catch blocks for it if the relevant
   parameters could be erroneous.

   Standard Java practice is to encode every exceptional condition as a
   separate subclass of Exception.  Because of the relatively high cost
   in code size of Exception subclasses, the API contains only a single
   Exception subclass with different conditions being determined by an
   integer error code property.  A subset, appropriate to Java, of the
   error codes described in Section 3 are available as constants on the
   ServiceLocationException class.  The subset excludes error codes such

Top      Up      ToC       Page 57 
   as MEMORY_ALLOC_FAILED.

5.2.1. Class ServiceLocationException

5.2.1.1. Synopsis


   public class ServiceLocationException
   extends Exception


5.2.1.2. Description

   The ServiceLocationException class is thrown by all methods when
   exceptional conditions occur in the SLP framework.  The error code
   property determines the exact nature of the condition, and an
   optional message may provide more information.

5.2.1.3. Fields


   public static final short LANGUAGE_NOT_SUPPORTED = 1
   public static final short PARSE_ERROR = 2
   public static final short INVALID_REGISTRATION = 3
   public static final short SCOPE_NOT_SUPPORTED = 4
   public static final short AUTHENTICATION_ABSENT = 6
   public static final short AUTHENTICATION_FAILED = 7
   public static final short INVALID_UPDATE = 13
   public static final short REFRESH_REJECTED = 15
   public static final short NOT_IMPLEMENTED = 16
   public static final short NETWORK_INIT_FAILED 17
   public static final short NETWORK_TIMED_OUT = 18
   public static final short NETWORK_ERROR = 19
   public static final short INTERNAL_SYSTEM_ERROR = 20
   public static final short TYPE_ERROR = 21
   public static final short BUFFER_OVERFLOW = 22


5.2.1.4. Instance Methods


   public short getErrorCode()


   Return the error code.  The error code takes on one of the static
   field values.

Top      Up      ToC       Page 58 
5.3. Basic Data Structures

5.3.1. Interface ServiceLocationEnumeration


   public interface ServiceLocationEnumeration
    extends Enumeration


5.3.1.1. Description

   The ServiceLocationEnumeration class is the return type for all
   Locator SLP operations.  The Java API library may implement this
   class to block until results are available from the SLP operation, so
   that the client can achieve asynchronous operation by retrieving
   results from the enumeration in a separate thread.  Clients use the
   superclass nextElement() method if they are unconcerned with SLP
   exceptions.

5.3.1.2. Instance Methods


   public abstract Object next() throws ServiceLocationException

   Return the next value or block until it becomes available.

   Throws:

      ServiceLocationException

         Thrown if the SLP operation encounters an error.

      NoSuchElementException

         If there are no more elements to return.


5.3.2. Class ServiceLocationAttribute

5.3.2.1. Synopsis


   public class ServiceLocationAttribute
     extends Object implements Serializable

Top      Up      ToC       Page 59 
5.3.2.2. Description

   The ServiceLocationAttribute class models SLP attributes.  Instances
   of this class are returned by Locator.findAttributes() and are
   communicated along with register/deregister requests.

5.3.2.3. Constructors


   public ServiceLocationAttribute(String id,Vector values)


   Construct a service location attribute.  Errors in the id or values
   vector result in an IllegalArgumentException.

   Parameters:

      id

         The attribute name.  The String can consist of any Unicode
         character.

      values

         A Vector of one or more attribute values.  Vector contents
         must be uniform in type and one of Integer, String, Boolean,
         or byte[].  If the attribute is a keyword attribute, then the
         parameter should be null.  String values can consist of any
         Unicode character.


5.3.2.4. Class Methods


   public static String escapeId(String id)


   Returns an escaped version of the id parameter, suitable for
   inclusion in a query.  Any reserved characters as specified in [7]
   are escaped using UTF-8 encoding.  If any characters in the tag are
   illegal, throws IllegalArgumentException.

   Parameters:

      id

         The attribute id to escape.  ServiceLocationException is thrown
         if any characters are illegal for an attribute tag.

Top      Up      ToC       Page 60 
   public static String escapeValue(Object value)


   Returns a String containing the escaped value parameter as a string,
   suitable for inclusion in a query.  If the parameter is a string,
   any reserved characters as specified in [7] are escaped using UTF-8
   encoding.  If the parameter is a byte array, then the escaped string
   begins with the nonUTF-8 sequence `\ff` and the rest of the string
   consists of the escaped bytes, which is the encoding for opaques.
   If the value parameter is a Boolean or Integer, then the returned
   string contains the object converted into a string.  If the value
   is any type other than String, Integer, Boolean or byte[], an
   IllegalArgumentException is thrown.

   Parameters:

      value

         The attribute value to be converted into a string and escaped.


5.3.2.5. Instance Methods


   public Vector getValues()


   Returns a cloned vector of attribute values, or null if the attribute
   is a keyword attribute.  If the attribute is single-valued, then the
   vector contains only one object.


   public String getId()


   Returns the attribute's name.


   public boolean equals(Object o)


   Overrides Object.equals().  Two attributes are equal if their
   identifiers are equal and their value vectors contain the same number
   of equal values as determined by the Object equals() method.  Values
   having byte[] type are equal if the contents of all byte arrays in
   both attribute vectors match.  Note that the SLP string matching
   algorithm [7] MUST NOT be used for comparing attribute identifiers or
   string values.

Top      Up      ToC       Page 61 
   public String toString()


   Overrides Object.toString().  The string returned contains a
   formatted representation of the attribute, giving the attribute's
   id, values, and the Java type of the values.  The returned string is
   suitable for debugging purposes, but is not in SLP wire format.


   public int hashCode()


   Overrides Object.hashCode().  Hashes on the attribute's identifier.


5.3.3. Class ServiceType

5.3.3.1. Synopsis


   public class ServiceType extends Object implements Serializable


5.3.3.2. Description

   The ServiceType object models the SLP service type.  It parses a
   string based service type specifier into its various components, and
   contains property accessors to return the components.  URL schemes,
   protocol service types, and abstract service types are all handled.

5.3.3.3. Constructors


   public ServiceType(String type)


   Construct a service type object from the service type specifier.
   Throws IllegalArgumentException if the type name is syntactically
   incorrect.

   Parameters:

      type

         The service type name as a String.  If the service type is from
         a service:  URL, the "service:" prefix must be intact.

Top      Up      ToC       Page 62 
5.3.3.4. Methods


   public boolean isServiceURL()


   Returns true if the type name contains the "service:" prefix.


   public boolean isAbstractType()


   Returns true if the type name is for an abstract type.


   public boolean isNADefault()

   Returns true if the naming authority is the default, i.e.  is the
   empty string.


   public String getConcreteTypeName()


   Returns the concrete type name in an abstract type, or the empty
   string if the service type is not abstract.  For example, if the type
   name is "service:printing:ipp", the method returns "ipp".  If the
   type name is "service:ftp", the method returns "".


   public String getPrincipleTypeName()


   Returns the abstract type name for an abstract type, the protocol
   name in a protocol type, or the URL scheme for a generic URL. For
   example, in the abstract type name "service:printing:ipp", the method
   returns "printing".  In the protocol type name "service:ftp", the
   method returns "ftp".


   public String getAbstractTypeName()


   If the type is an abstract type, returns the fully formatted abstract
   type name including the "service:" and naming authority but without
   the concrete type name or intervening colon.  If not an abstract
   type, returns the empty string.  For example, in the abstract type
   name "service:printing:ipp", the method returns "service:printing".

Top      Up      ToC       Page 63 
   public String getNamingAuthority()


   Return the naming authority name, or the empty string if the naming
   authority is the default.


   public boolean equals(Object obj)


   Overrides Object.equals().  The two objects are equal if they are
   both ServiceType objects and the components of both are equal.


   public String toString()


   Returns the fully formatted type name, including the "service:" if
   the type was originally from a service:  URL.


   public int hashCode()


   Overrides Object.hashCode().  Hashes on the string value of the
   "service" prefix, naming authority, if any, abstract and concrete
   type names for abstract types, protocol type name for protocol types,
   and URL scheme for generic URLs.


5.3.4. Class ServiceURL

5.3.4.1. Synopsis


   public class ServiceURL extends Object implements Serializable


5.3.4.2. Description

   The ServiceURL object models the advertised SLP service URL. It can
   be either a service:  URL or a regular URL. These objects are
   returned from service lookup requests, and describe the registered
   services.  This class should be a subclass of java.net.URL but can't
   since that class is final.

Top      Up      ToC       Page 64 
5.3.4.3. Class Variables


   public static final int NO_PORT = 0


   Indicates that no port information is required or was returned for
   this URL.


   public static final int LIFETIME_NONE = 0


   Indicates that the URL has a zero lifetime.  This value is never
   returned from the API, but can be used to create a ServiceURL object
   to deregister, delete attributes, or find attributes.


   public static final int LIFETIME_DEFAULT = 10800


   The default URL lifetime (3 hours) in seconds.


   public static final int LIFETIME_MAXIMUM = 65535


   The maximum URL lifetime (about 18 hours) in seconds.


   public static final int LIFETIME_PERMANENT = -1


   Indicates that the API implementation should continuously re-register
   the URL until the application exits.


5.3.4.4. Constructors


   public ServiceURL(String URL,int lifetime)


   Construct a service URL object having the specified lifetime.

Top      Up      ToC       Page 65 
   Parameters:

      URL

         The URL as a string.  Must be either a service:  URL or a valid
         generic URL according to RFC 2396 [2].

      lifetime

         The service advertisement lifetime in seconds.  This value may
         be between LIFETIME_NONE and LIFETIME_MAXIMUM.


5.3.4.5. Methods


   public ServiceType getServiceType()


   Returns the service type object representing the service type name of
   the URL.


  public final void setServiceType(ServiceType type)
  throws ServiceLocationException


   Set the service type name to the object.  Ignored if the URL is a
   service:  URL.

   Parameters:

      type

         The service type object.


   public String getTransport()


   Get the network layer transport identifier.  If the transport is IP,
   an empty string, "", is returned.


   public String getHost()

Top      Up      ToC       Page 66 
   Returns the host identifier.  For IP, this will be the machine name
   or IP address.


   public int getPort()


   Returns the port number, if any.  For non-IP transports, always
   returns NO_PORT.


   public String getURLPath()


   Returns the URL path description, if any.


   public int getLifetime()


   Returns the service advertisement lifetime.  This will be a positive
   int between LIFETIME_NONE and LIFETIME_MAXIMUM.


   public boolean equals(Object obj)


   Compares the object to the ServiceURL and returns true if the two are
   the same.  Two ServiceURL objects are equal if their current service
   types match and they have the same host, port, transport, and URL
   path.


   public String toString()


   Returns a formatted string with the URL. Overrides Object.toString().
   The returned URL has the original service type or URL scheme, not the
   current service type.


   public int hashCode()


   Overrides Object.hashCode().  Hashes on the current service type,
   transport, host, port, and URL part.

Top      Up      ToC       Page 67 
5.4. SLP Access Interfaces

5.4.1. Interface Advertiser

5.4.1.1. Synopsis


   public interface Advertiser


5.4.1.2. Description

   The Advertiser is the SA interface, allowing clients to register new
   service instances with SLP, to change the attributes of existing
   services, and to deregister service instances.  New registrations and
   modifications of attributes are made in the language locale with
   which the Advertiser was created, deregistrations of service
   instances are made for all locales.

5.4.1.3. Instance Methods


   public abstract Locale getLocale()


   Return the language locale with which this object was created.


   public abstract void register(ServiceURL URL,
                                 Vector attributes)
   throws ServiceLocationException

   Register a new service with SLP having the given attributes.

   The API library is required to perform the operation in all
   scopes obtained through configuration.


   Parameters:

      URL

         The URL for the service.

      attributes

         A vector of ServiceLocationAttribute objects describing the
         service.

Top      Up      ToC       Page 68 
   public abstract void deregister(ServiceURL URL)
   throws ServiceLocationException


   Deregister a service from the SLP framework.  This has the effect
   of deregistering the service from every language locale.  The API
   library is required to perform the operation in all scopes obtained
   through configuration.

   Parameters:

      URL

         The URL for the service.


   public abstract void
   addAttributes(ServiceURL URL,
                 Vector attributes)
   throws ServiceLocationException


   Update the registration by adding the given attributes.  The API
   library is required to perform the operation in all scopes obtained
   through configuration.

   Parameters:

      URL

         The URL for the service.

      attributes

         A Vector of ServiceLocationAttribute objects to add to the
         existing registration.  Use an empty vector to update the URL
         alone.  May not be null.


   public abstract void
   deleteAttributes(ServiceURL URL,
                    Vector attributeIds)
   throws ServiceLocationException


   Delete the attributes from a URL for the locale with which the
   Advertiser was created.  The API library is required to perform the
   operation in all scopes obtained through configuration.

Top      Up      ToC       Page 69 
   Parameters:

      URL

         The URL for the service.

      attributeIds

         A vector of Strings indicating the ids of the attributes
         to remove.  The strings may be attribute ids or they
         may be wildcard patterns to match ids.  See [7] for the
         syntax of wildcard patterns.  The strings may include SLP
         reserved characters, they will be escaped by the API before
         transmission.  May not be the empty vector or null.


5.4.2. Interface Locator

5.4.2.1. Synopsis


   public interface Locator


5.4.2.2. Description

   The Locator is the UA interface, allowing clients to query the SLP
   framework about existing service types, services instances, and about
   the attributes of an existing service instance or service type.
   Queries for services and attributes are made in the locale with which
   the Locator was created, queries for service types are independent of
   locale.

5.4.2.3. Instance Methods


   public abstract Locale getLocale()


   Return the language locale with which this object was created.


   public abstract ServiceLocationEnumeration
   findServiceTypes(String namingAuthority,
                    Vector scopes)
   throws ServiceLocationException

Top      Up      ToC       Page 70 
   Returns an enumeration of ServiceType objects giving known service
   types for the given scopes and given naming authority.  If no service
   types are found, an empty enumeration is returned.

   Parameters:

      namingAuthority

         The naming authority.  Use "" for the default naming authority
         and "*" for all naming authorities.

      scopes

         A Vector of scope names.  The vector should be selected from
         the results of a findScopes() API invocation.  Use "DEFAULT"
         for the default scope.


   public abstract ServiceLocationEnumeration
   findServices(ServiceType type,
                Vector scopes,
                String searchFilter)
   throws ServiceLocationException


   Returns a vector of ServiceURL objects for services matching the
   query, and having a matching type in the given scopes.  If no
   services are found, an empty enumeration is returned.

   Parameters:

      type

         The SLP service type of the service.

      scopes

         A Vector of scope names.  The vector should be selected from
         the results of a findScopes() API invocation.  Use "DEFAULT"
         for the default scope.

      searchFilter

         An LDAPv3 [4] string encoded query.  If the filter is empty,
         i.e.  "", all services of the requested type in the specified
         scopes are returned.  SLP reserved characters must be escaped
         in the query.  Use ServiceLocationAttribute.escapeId() and
         ServiceLocationAttribute.escapeValue() to construct the query.

Top      Up      ToC       Page 71 
   public abstract ServiceLocationEnumeration
   findAttributes(ServiceURL URL,
                  Vector scopes,
                  Vector attributeIds)
   throws ServiceLocationException


   For the URL and scope, return a Vector of ServiceLocationAttribute
   objects whose ids match the String patterns in the attributeIds
   Vector.  The request is made in the language locale of the Locator.
   If no attributes match, an empty enumeration is returned.

   Parameters:

      URL

         The URL for which the attributes are desired.

      scopes

         A Vector of scope names.  The vector should be selected from
         the results of a findScopes() API invocation.  Use "DEFAULT"
         for the default scope.

      attributeIds

         A Vector of String patterns identifying the desired attributes.
         An empty vector means return all attributes.  As described
         in [7], the patterns may include wildcards to match substrings.
         The strings may include SLP reserved characters, they will be
         escaped by the API before transmission.


   public abstract ServiceLocationEnumeration
   findAttributes(ServiceType type,
                  Vector scopes,
                  Vector attributeIds)
   throws ServiceLocationException


   For the type and scope, return a Vector of all ServiceLocationAttribute
   objects whose ids match the String patterns in the attributeIds
   Vector regardless of the Locator's locale.  The request is made
   independent of language locale.  If no attributes are found, an empty
   vector is returned.

Top      Up      ToC       Page 72 
   Parameters:

      serviceType

         The service type.

      scopes

         A Vector of scope names.  The vector should be selected from
         the results of a findScopes() API invocation.  Use "DEFAULT"
         for the default scope.

      attributeIds

         A Vector of String patterns identifying the desired
         attributes.  An empty vector means return all attributes.
         As described in [7], the patterns may include wildcards to
         match all prefixes or suffixes.  The patterns may include SLP
         reserved characters, they will be escaped by the API before
         transmission.

5.5. The Service Location Manager

5.5.1. Class ServiceLocationManager

5.5.1.1. Synopsis


    public class ServiceLocationManager
    extends Object


5.5.1.2. Description

   The ServiceLocationManager manages access to the service location
   framework.  Clients obtain the Locator and Advertiser objects for UA
   and SA, and a Vector of known scope names from the
   ServiceLocationManager.

5.5.1.3. Class Methods


   public static int getRefreshInterval()
   throws ServiceLocationException

Top      Up      ToC       Page 73 
   Returns the maximum across all DAs of the min-refresh-interval
   attribute.  This value satisfies the advertised refresh interval
   bounds for all DAs, and, if used by the SA, assures that no
   refresh registration will be rejected.  If no DA advertises a
   min-refresh-interval attribute, a value of 0 is returned.


   public static Vector findScopes()
   throws ServiceLocationException


   Returns an Vector of strings with all available scope names.  The
   list of scopes comes from a variety of sources, see Section 2.1 for
   the scope discovery algorithm.  There is always at least one string
   in the Vector, the default scope, "DEFAULT".


   public static Locator
   getLocator(Locale locale)
   throws ServiceLocationException


   Return a Locator object for the given language Locale.  If the
   implementation does not support UA functionality, returns null.

   Parameters:

      locale

         The language locale of the Locator.  The default SLP locale is
         used if null.


   public static Advertiser
   getAdvertiser(Locale locale)
   throws ServiceLocationException


   Return an Advertiser object for the given language locale.  If the
   implementation does not support SA functionality, returns null.

   Parameters:

      locale

         The language locale of the Advertiser.  The default SLP locale
         is used if null.

Top      Up      ToC       Page 74 
5.6. Service Template Introspection

5.6.1. Abstract Class TemplateRegistry

5.6.1.1. Synopsis


   public abstract class TemplateRegistry


5.6.1.2. Description

   Subclasses of the TemplateRegistry abstract class provide access to
   service location templates [8].  Classes implementing
   TemplateRegistry perform a variety of functions.  They manage the
   registration and access of service type template documents.  They
   create attribute verifiers from service templates, for verification
   of attributes and introspection on template documents.  Note that
   clients of the Advertiser are not required to verify attributes
   before registering (though they may get a TYPE_ERROR if the
   implementation supports type checking and there is a mismatch with
   the template).

5.6.1.3. Class Methods


   public static TemplateRegistry getTemplateRegistry();


   Returns the distinguished TemplateRegistry object for performing
   operations on and with service templates.  Returns null if the
   implementation doesn't support TemplateRegistry functionality.

5.6.1.4. Instance Methods


   public abstract void
   registerServiceTemplate(ServiceType type,
                           String documentURL,
                           Locale locale,
                           String version)
   throws ServiceLocationException


   Register the service template with the template registry.

Top      Up      ToC       Page 75 
   Parameters:

      type

         The service type.

      documentURL

         A string containing the URL of the template document.  May not
         be the empty string.

      locale

         A Locale object containing the language locale of the template.

      version

         The version number identifier of template document.


   public abstract void


   deregisterServiceTemplate(ServiceType type,
                             Locale locale,
                             String version)
   throws ServiceLocationException


   Deregister the template for the service type.

   Parameters:

      type

         The service type.

      locale

         A Locale object containing the language locale of the template.

      version

         A String containing the version number.  Use null to indicate
         the latest version.

Top      Up      ToC       Page 76 
   public abstract
   String findTemplateURL(ServiceType type,
                          Locale locale,
                          String version)
   throws ServiceLocationException


   Returns the URL for the template document.

   Parameters:

      type

         The service type.

      locale

         A Locale object containing the language locale of the template.

      version

         A String containing the version number.  Use null to indicate
         the latest version.


   public abstract
   ServiceLocationAttributeVerifier
   attributeVerifier(String documentURL)
   throws ServiceLocationException


   Reads the template document URL and returns an attribute verifier
   for the service type.  The attribute verifier can be used for
   verifying that registration attributes match the template, and for
   introspection on the template definition.

   Parameters:

      documentURL

         A String containing the template document's URL. May not be the
         empty string.

Top      Up      ToC       Page 77 
5.6.2. Interface ServiceLocationAttributeVerifier

5.6.2.1. Synopsis


   public interface ServiceLocationAttributeVerifier


5.6.2.2. Description

   The ServiceLocationAttributeVerifier provides access to service
   templates.  Classes implementing this interface parse SLP template
   definitions, provide information on attribute definitions for service
   types, and verify whether a ServiceLocationAttribute object matches a
   template for a particular service type.  Clients obtain
   ServiceLocationAttributeVerifier objects for specific SLP service
   types through the TemplateRegistry.

5.6.2.3. Instance Methods


   public abstract ServiceType getServiceType()


   Returns the SLP service type for which this is the verifier.


   public abstract Locale getLocale()


   Return the language locale of the template.


   public abstract String getVersion()


   Return the template version number identifier.


   public abstract String getURLSyntax()


   Return the URL syntax expression for the service:  URL.


   public abstract String getDescription()

Top      Up      ToC       Page 78 
   Return the descriptive help text for the template.


   public abstract ServiceLocationAttributeDescriptor
   getAttributeDescriptor(String attrId)


   Return the ServiceLocationAttributeDescriptor for the attribute
   having the named id.  If no such attribute exists in this template,
   return null.  This method is primarily for GUI tools to display
   attribute information.  Programmatic verification of attributes
   should use the verifyAttribute() method.


   public abstract Enumeration
   getAttributeDescriptors()


   Returns an Enumeration allowing introspection on the attribute
   definition in the service template.  The Enumeration returns
   ServiceLocationAttributeDescriptor objects for the attributes.
   This method is primarily for GUI tools to display attribute
   information.  Programmatic verification of attributes should use the
   verifyAttribute() method.


   public abstract void
   verifyAttribute(
     ServiceLocationAttribute attribute)
   throws ServiceLocationException


   Verify that the attribute matches the template definition.  If the
   attribute doesn't match, ServiceLocationException is thrown with the
   error code as ServiceLocationException.PARSE_ERROR.

   Parameters:

      attribute

         The ServiceLocationAttribute object to be verified.


   public abstract void
   verifyRegistration(
     Vector attributeVector)
   throws ServiceLocationException

Top      Up      ToC       Page 79 
   Verify that the Vector of ServiceLocationAttribute objects matches
   the template for this service type.  The vector must contain all the
   required attributes, and all attributes must match their template
   definitions.  If the attributes don't match, ServiceLocationException
   is thrown with the error code as ServiceLocationException.PARSE_ERROR

   Parameters:

      attributeVector

         A Vector of ServiceLocationAttribute objects for the
         registration.


5.6.3. Interface ServiceLocationAttributeDescriptor

5.6.3.1. Synopsis


   public interface
   ServiceLocationAttributeDescriptor


5.6.3.2. Description

   The ServiceLocationAttributeDescriptor interface provides
   introspection on a template attribute definition.  Classes
   implementing the ServiceLocationAttributeDescriptor interface return
   information on a particular service location attribute definition
   from the service template.  This information is primarily for GUI
   tools.  Programmatic attribute verification should be done through
   the ServiceLocationAttributeVerifier.

5.6.3.3. Instance Methods


   public abstract String getId()


   Return a String containing the attribute's id.


   public abstract String getValueType()


   Return a String containing the fully package-qualified Java type of
   the attribute.  SLP types are translated into Java types as follows:

Top      Up      ToC       Page 80 
      STRING

         "java.lang.String"

      INTEGER

         "java.lang.Integer"

      BOOLEAN

         "java.lang.Boolean"

      OPAQUE

         "[B" (i.e.  array of byte, byte[])

      KEYWORD

         empty string, ""


 public abstract String getDescription()


   Return a String containing the attribute's help text.


   public abstract Enumeration
   getAllowedValues()


   Return an Enumeration of allowed values for the attribute type.
   For keyword attributes returns null.  For no allowed values (i.e.
   unrestricted) returns an empty Enumeration.


   public abstract Enumeration
   getDefaultValues()


   Return an Enumeration of default values for the attribute type.
   For keyword attributes returns null.  For no allowed values (i.e.
   unrestricted) returns an empty Enumeration.


   public abstract boolean
   getRequiresExplicitMatch()

Top      Up      ToC       Page 81 
   Returns true if the "X"" flag is set, indicating that the attribute
   should be included in an any Locator.findServices() request search
   filter.


   public abstract boolean getIsMultivalued()


   Returns true if the "M" flag is set.


   public abstract boolean getIsOptional()


   Returns true if the "O"" flag is set.


   public abstract boolean getIsLiteral()


   Returns true if the "L" flag is set.


   public abstract boolean getIsKeyword()


   Returns true if the attribute is a keyword attribute.


5.7. Implementation Notes

5.7.1. Refreshing Registrations

   A special lifetime constant, ServiceURL.LIFETIME_PERMANENT, is used
   by clients to indicate that the URL should be automatically refreshed
   until the application exits.  The API implementation should interpret
   this flag as indicating that the URL lifetime is
   ServiceURL.LIFETIME_MAXIMUM, and MUST arrange for automatic refresh
   to occur.

5.7.2. Parsing Alternate Transports in ServiceURL

   The ServiceURL class is designed to handle multiple transports.  The
   standard API performs no additional processing on transports other
   than IP except to separate out the host identifier and the URL path.
   However, implementations are free to subclass ServiceURL and support
   additional methods that provide more detailed parsing of alternate
   transport information.  For IP transport, the port number, if any, is

Top      Up      ToC       Page 82 
   returned from the getPort() method.  For non-IP transports, the
   getPort() method returns NO_PORT.

5.7.3. String Attribute Values

   In general, translation between Java types for attribute values and
   the SLP on-the-wire string is straightforward.  However, there are
   two corner cases.  If the Java attribute value type is String and the
   value of the string has an on-the-wire representation that is
   inferred by SLP as an integer, the registered attribute value may not
   be what the API client intended.  A similar problem could result if
   the Java attribute value is the string "true" or "false", in which
   case the on-the-wire representation is inferred to boolean.  To
   handle these corner cases, the Java API prepends a space onto the
   string.  So, for example, if the string attribute value is "123", the
   Java API transforms the value to "123 ", which will have an on-the-
   wire representation that is inferred by SLP to be string.  Since
   appended and prepended spaces have no effect on query handling, this
   procedure should cause no problem with queries.  API clients need to
   be aware, however, that the transformation is occurring.

5.7.4. Client Side Syntax Checking

   The syntax of scope names, service type names, naming authority
   names, and URLs is described in [7] and [8].  The various methods and
   classes taking String parameters for these entities SHOULD type check
   the parameters for syntax errors on the client side, and throw an
   IllegalArgumentException if an error occurs.  In addition, character
   escaping SHOULD be implemented before network transmission for
   escapable characters in attribute ids and String values.  This
   reduces the number of error messages transmitted.  The
   ServiceLocationAttribute class provides methods for clients to obtain
   escaped attribute id and value strings to facilitate query
   construction.

5.7.5. Language Locale Handling

   The Locator and Advertiser interfaces are created with a Locale
   parameter.  The language locale with which these objects are created
   is used in all SLP requests issued through the object.  If the Locale
   parameter is null, the default SLP locale is used.  The default SLP
   locale is determined by, first, checking the net.slp.locale System
   property.  If that is unset, then the default SLP locale [7] is used,
   namely "en".  Note that the default SLP locale may not be the same as
   the default Java locale.

Top      Up      ToC       Page 83 
5.7.6. Setting SLP System Properties

   SLP system properties that are originally set in the configuration
   file can be overridden programmatically in API clients by simply
   invoking the System.getProperties() operation to get a copy of the
   system properties, modifying or adding the SLP property in question,
   then using System.setProperties() to set the properties to the
   modified Property object.  Program execution continues without
   interruption by substituting the default for the erroneous parameter.
   Errors are checked when the property is used and are logged.

   The SLP configuration file cannot be read with the
   java.util.Properties file reader because there are some syntactic
   differences.  The SLP configuration file syntax defines a different
   escape convention for non-ASCII characters than the Java syntax.
   However, after the file has been read, the properties are stored and
   retrieved from java.util.Properties objects.

   Properties are global for a process, affecting all threads and all
   Locator and Advertiser objects obtained through the
   ServiceLocationManager.  With the exception of the net.slp.locale,
   net.slp.typeHint, and net.slp.maxResults properties, clients should
   rarely be required to override these properties, since they reflect
   properties of the SLP network that are not of concern to individual
   agents.  If changes are required, system administrators should modify
   the configuration file.

5.7.7. Multithreading

   Thread-safe operation is relatively easy to achieve in Java.  By
   simply making each method in the classes implementing the Locator and
   Advertiser interfaces synchronized, and by synchronizing access to
   any shared data structures within the class, the Locator and
   Advertiser interfaces are made safe.  Alternatively, finer grained
   synchronization is also possible within the classes implementing
   Advertiser and Locator.

5.7.8. Modular Implementations

   While, at first glance, the API may look rather heavyweight, the
   design has been carefully arranged so that modular implementations
   that provide only SA, only UA, or only service template access
   capability, or any combination of the three, are possible.

   Because the objects returned from the
   ServiceLocationManager.getLocator() and
   ServiceLocationManager.getAdvertiser() operations are interfaces, and
   because the objects returned through those interfaces are in the set

Top      Up      ToC       Page 84 
   of base data structures, an implementation is free to omit either UA
   or SA capability by simply returning null from the instance creation
   operation if the classes implementing the missing function cannot be
   dynamically linked.  API clients are encouraged to check for such a
   contingency, and to signal an exception if it occurs.  Similarly, the
   TemplateRegistry concrete subclass can simply be omitted from an
   implementation that only supports UA and/or SA clients, and the
   TemplateRegistry.getRegistry() method can return null.  In this way,
   the API implementation can be tailored for the particular memory
   requirements at hand.

   In addition, if an implementation only supports the minimal subset of
   SLP [7], the unsupported Locator and Advertiser interface operations
   can throw an exception with ServiceLocationException.NOT_IMPLEMENTED
   as the error code.  This supports better source portability between
   low and high memory platforms.

5.7.9. Asynchronous and Incremental Return Semantics

   The Java API contains no specific support for asynchronous operation.
   Incremental return is not needed for the Advertiser because service
   registrations can be broken up into pieces when large.  Asynchronous
   return is also not needed because clients can always issue the
   Advertiser operation in a separate thread if the calling thread can't
   block.

   The Locator can be implemented either synchronously or
   asynchronously.  Since the return type for Locator calls is
   ServiceLocationEnumeration, a Java API implementation that supports
   asynchronous semantics can implement ServiceLocationEnumeration to
   dole results out as they come in, blocking when no results are
   available.  If the client code needs to support other processing
   while the results are trickling in, the call into the enumeration to
   retrieve the results can be done in a separate thread.

   Unlike the C case, collation semantics for return of attributes when
   an attribute request by service type is made require that the API
   collate returned values so that only one attribute having a collation
   of all returned values appear to the API client.  In practice, this
   may limit the amount of asynchronous processing possible with the
   findAttributes() method.  This requirement is imposed because memory
   management is much easier in Java and so implementing collation as
   part of the API should not be as difficult as in C, and it saves the
   client from having to do the collation.

Top      Up      ToC       Page 85 
5.8. Example

   In this example, a printer server advertises its availability to
   clients.  Additionally, the server advertises a service template for
   use by client software in validating service requests:


  //Get the Advertiser and TemplateRegistry.

  Advertiser adv = null;
  TemplateRegistry tr = null

  try {

    adv = ServiceLocationManager.getAdvertiser("en");

    tr = TemplateRegistry.getTemplateRegistry();

  } catch( ServiceLocationException ex ) { } //Deal with error.

  if( adv == null ) {

    //Serious error as printer can't be registered
    //  if the implementation doesn't support SA
    //  functionality.

  }

  //Get the printer's attributes, from a file or
  //  otherwise. We assume that the attributes
  //  conform to the template, otherwise, we
  //  could register the template here and verify
  //  them.

  Vector attributes = getPrinterAttributes();

  //Create the service: URL for the printer.

  ServiceURL printerURL =
    new ServiceURL(
      "service:printer:lpr://printshop/color2",
      ServiceURL.LIFETIME_MAXIMUM);

  try {

    //Register the printer.

    adv.register(printerURL, attributes);

Top      Up      ToC       Page 86 
    //If the template registry is available,
    //  register the printer's template.

    if( tr != null ) {
      tr.registerServiceTemplate(
        new ServiceType("service:printer:lpr"),
        "http://shop.arv/printer/printer-lpr.slp",
        new Locale("en",""),
        "1.0");

   }

  } catch( ServiceLocationException ex ) { } //Deal with error.


   Suppose a client is looking for color printer.  The following code is
   used to issue a request for printer advertisements:


  Locator loc = null;
  TemplateRegistry tr = null;

  try {

    loc = ServiceLocationManager.getLocator("en");

  } catch( ServiceLocationException ex ) { } //Deal with error.

  if( loc == null ) {

    //Serious error as client can't be located
    //  if the implementation doesn't support
    //  UA functionality.

  }

  //We want a color printer that does CMYK
  //  and prints at least 600 dpi.

  String query = "(&(marker-type=CMYK)(resolution=600))";

  //Get scopes.

  Vector scopes = ServiceLocationManager.findScopes();

  Enumeration services;

  try {

Top      Up      ToC       Page 87 
    services =
      loc.findServices(new ServiceType("service:printer"),scopes,query);

  } catch { } //Deal with error.

  if (services.hasMoreElements() ) {

    //Printers can now be used.
    ServiceURL surl = (ServiceURL) services.next();

    Socket sock = new Socket(surl.getHost, surl.getPort());

    // Use the Socket...

  }


6. Internationalization Considerations

6.1. service URL

   The service URL itself must be encoded using the rules set forth in
   [2].  The character set encoding is limited to specific ranges within
   the UTF-8 character set [3].

   The attribute information associated with the service URL must be
   expressed in UTF-8.  See [8] for attribute internationalization
   guidelines.

6.2. Character Set Encoding

   Configuration and serialized registration files are encoded in the
   UTF-8 character set [3].  This is fully compatible with US-ASCII
   character values.  C platforms that do not support UTF-8 are required
   to check the top bit of input bytes to determine whether the incoming
   character is multibyte.  If it is, the character should be dealt with
   accordingly.  This should require no additional implementation
   effort, since the SLP wire protocol requires that strings are encoded
   as UTF-8.  C platforms without UTF-8 support need to supply their own
   support, if only in the form of multibyte string handling.

   At the API level, the character encoding is specified to be Unicode
   for Java and UTF-8 for C. Unicode is the default in Java.  For C, the
   standard US-ASCII 8 bits per character, null terminated C strings are
   a subset of the UTF-8 character set, and so work in the API. Because
   the C API is very simple, the API library needs to do a minimum of
   processing on UTF-8 strings.  The strings primarily just need to be
   reflected into the outgoing SLP messages, and reflected out of the

Top      Up      ToC       Page 88 
   API from incoming SLP messages.

6.3. Language Tagging

   All SLP requests and registrations are tagged to indicate in which
   language the strings included are encoded.  This allows multiple
   languages to be supported.  It also presents the possibility that
   error conditions result when a request is made in a language that is
   not supported.  In this case, an error is only returned when there is
   data available, but not obtainable in the language requested.

   The dialect portion of the Language Tag is used on 'best effort'
   basis for matching strings by SLP. Dialects that match are preferred
   over those which don't.  Dialects that do not match will not prevent
   string matching or comparisons from occurring.

7. Security Considerations

   Security is handled within the API library and is not exposed to API
   clients except in the form of exceptions.  The
   net.slp.securityEnabled, property determines whether an SA client's
   messages are signed, but a UA client should be prepared for an
   authentication exception at any time, because it may contact a DA
   with authenticated advertisements.

   An adversary could delete valid service advertisements, provide false
   service information and deny UAs knowledge of existing services
   unless the mechanisms in SLP for authenticating SLP messages are
   used.  These mechanisms allow DAAdverts, SAAdverts, Service URLs and
   Service Attributes to be verified using digital cryptography.  For
   this reason, all SLP agents should be configured to use SLP SPIs.
   See [7] for a description of how this mechanism works.

8. Acknowledgements

   The authors would like to thank Don Provan for his pioneering work
   during the initial stages of API definition.

Top      Up      ToC       Page 89 
9. References

    [1] Bradner, S., "Key Words for Use in RFCs to Indicate
        Requirement Levels", BCP 14, RFC 2119, March 1997.

    [2] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
        Resource Identifiers (URI): Generic Syntax", RFC 2396,
        August 1998.

    [3] Yergeau, F., "UTF-8, a transformation format of ISO 10646",
        RFC 2279, January 1998.

    [4] Howes, T., "The String Representation of LDAP Search Filters",
        RFC 2254  December 1997.

    [5] Crocker, D. and P. Overell, "Augmented BNF for Syntax
        Specifications: ABNF", RFC 2234, November 1997.

    [6] Alvestrand, H., "Tags for the Identification of Languages",
        RFC 1766, March 1995.

    [7] Guttman, E., Perkins, C., Veizades, J. and M. Day, "Service
        Location Protocol, Version 2", RFC 2608, June 1999.

    [8] Guttman, E., Perkins, C. and J. Kempf, "Service Templates and
        Service: Schemes", RFC 2609, June 1999.

Top      Up      ToC       Page 90 
10. Authors' Addresses

   Questions about this memo can be directed to:

   James Kempf
   Sun Microsystems
   901 San Antonio Rd.
   Palo Alto, CA, 94303
   USA

   Phone: +1 650 786 5890
   Fax:   +1 650 786 6445
   EMail: james.kempf@sun.com


   Erik Guttman
   Sun Microsystems
   Bahnstr. 2
   74915 Waibstadt
   Germany

   Phone: +49 7263 911 701
   EMail: erik.guttman@sun.com

Top      Up      ToC       Page 91 
11. Full Copyright Statement

   Copyright (C) The Internet Society (1999).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."

Acknowledgement

   Funding for the RFC Editor function is currently provided by the
   Internet Society.