Skip to main content

An API for Service Location
RFC 2614

Document Type RFC - Informational (June 1999)
Authors Erik Guttman , James Kempf
Last updated 2013-03-02
RFC stream Internet Engineering Task Force (IETF)
Formats
Additional resources Mailing list discussion
IESG Responsible AD (None)
Send notices to (None)
RFC 2614

   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()

Kempf & Guttman              Informational                     [Page 65]
RFC 2614                  Service Location API                 June 1999

   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.

Kempf & Guttman              Informational                     [Page 66]
RFC 2614                  Service Location API                 June 1999

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.

Kempf & Guttman              Informational                     [Page 67]
RFC 2614                  Service Location API                 June 1999

   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.

Kempf & Guttman              Informational                     [Page 68]
RFC 2614                  Service Location API                 June 1999

   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

Kempf & Guttman              Informational                     [Page 69]
RFC 2614                  Service Location API                 June 1999

   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.

Kempf & Guttman              Informational                     [Page 70]
RFC 2614                  Service Location API                 June 1999

   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.

Kempf & Guttman              Informational                     [Page 71]
RFC 2614                  Service Location API                 June 1999

   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

Kempf & Guttman              Informational                     [Page 72]
RFC 2614                  Service Location API                 June 1999

   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.

Kempf & Guttman              Informational                     [Page 73]
RFC 2614                  Service Location API                 June 1999

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.

Kempf & Guttman              Informational                     [Page 74]
RFC 2614                  Service Location API                 June 1999

   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.

Kempf & Guttman              Informational                     [Page 75]
RFC 2614                  Service Location API                 June 1999

   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.

Kempf & Guttman              Informational                     [Page 76]
RFC 2614                  Service Location API                 June 1999

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()

Kempf & Guttman              Informational                     [Page 77]
RFC 2614                  Service Location API                 June 1999

   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

Kempf & Guttman              Informational                     [Page 78]
RFC 2614                  Service Location API                 June 1999

   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:

Kempf & Guttman              Informational                     [Page 79]
RFC 2614                  Service Location API                 June 1999

      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()

Kempf & Guttman              Informational                     [Page 80]
RFC 2614                  Service Location API                 June 1999

   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

Kempf & Guttman              Informational                     [Page 81]
RFC 2614                  Service Location API                 June 1999

   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.

Kempf & Guttman              Informational                     [Page 82]
RFC 2614                  Service Location API                 June 1999

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

Kempf & Guttman              Informational                     [Page 83]
RFC 2614                  Service Location API                 June 1999

   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.

Kempf & Guttman              Informational                     [Page 84]
RFC 2614                  Service Location API                 June 1999

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);

Kempf & Guttman              Informational                     [Page 85]
RFC 2614                  Service Location API                 June 1999

    //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 {

Kempf & Guttman              Informational                     [Page 86]
RFC 2614                  Service Location API                 June 1999

    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

Kempf & Guttman              Informational                     [Page 87]
RFC 2614                  Service Location API                 June 1999

   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.

Kempf & Guttman              Informational                     [Page 88]
RFC 2614                  Service Location API                 June 1999

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.

Kempf & Guttman              Informational                     [Page 89]
RFC 2614                  Service Location API                 June 1999

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

Kempf & Guttman              Informational                     [Page 90]
RFC 2614                  Service Location API                 June 1999

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.

Kempf & Guttman              Informational                     [Page 91]