com.tivoli.twg.engine.slp
Class ServiceUrl

java.lang.Object
  extended bycom.tivoli.twg.engine.slp.ServiceUrl

public final class ServiceUrl
extends java.lang.Object

SLP Service URL

from RFC 2608 (Service Location Protocol, Version 2):

Service: URLs

Service URL syntax and semantics are defined in [13]. Any network service may be encoded in a Service URL.

This section provides an introduction to Service URLs and an example showing a simple application of them, representing standard network services.

A Service URL may be of the form:

    "service:"<srvtype>"://"<addrspec>

The Service Type of this service: URL is defined to be the string up to (but not including) the final `:' before <addrspec>, the address specification.

<addrspec> is a hostname (which should be used if possible) or dotted decimal notation for a hostname, followed by an optional `:' and port number.

A service: scheme URL may be formed with any standard protocol name by concatenating "service:" and the reserved port [1] name. For example, "service:tftp://myhost" would indicate a tftp service. A tftp service on a nonstandard port could be "service:tftp://bad.glad.org:8080".

Service Types SHOULD be defined by a "Service Template" [13], which provides expected attributes, values and protocol behavior. An abstract service type (also described in [13]) has the form

    "service:<abstract-type>:<concrete-type>".

The service type string "service:<abstract-type>" matches all services of that abstract type. If the concrete type is included also, only these services match the request. For example: a SrvRqst or AttrRqst which specifies "service:printer" as the Service Type will match the URL service:printer:lpr://hostname and service:printer:http://hostname. If the requests specified "service:printer:http" they would match only the latter URL.

An optional substring MAY follow the last `.' character in the <srvtype> (or <abstract-type> in the case of an abstract service type URL). This substring is the Naming Authority, as described in Section 9.6. Service types with different Naming Authorities are quite distinct. In other words, service:x.one and service:x.two are different service types, as are service:abstract.one:y and service:abstract.two:y.

Naming Authorities

A Naming Authority MAY optionally be included as part of the Service Type string. The Naming Authority of a service defines the meaning of the Service Types and attributes registered with and provided by Service Location. The Naming Authority itself is typically a string which uniquely identifies an organization. IANA is the implied Naming Authority when no string is appended. "IANA" itself MUST NOT be included explicitly.

Naming Authorities may define Service Types which are experimental, proprietary or for private use. Using a Naming Authority, one may either simply ignore attributes upon registration or create a local- use only set of attributes for one's site. The procedure to use is to create a 'unique' Naming Authority string and then specify the Standard Attribute Definitions as described above. This Naming Authority will accompany registration and queries, as described in Sections 8.1 and 8.3. Service Types SHOULD be registered with IANA to allow for Internet-wide interoperability.

from RFC 2609 (Service Templates and Service: Schemes):

Service URL Syntax

The syntax of the service: URL MUST conform to an 'absolute URI' as defined by [5]. The syntax of a service: URL differs enough from a 'generic URI' that it is best to treat it as an opaque URI unless a specific parser for the service: URL is available.

All service: URLs have the same syntax up to the 'url-part' The syntax for a service URL depends on the service type following the service scheme. All service: URLs have a service access point portion, indicating the address of the service to access.

The syntax for the <sap> field depends upon the service type definition. The <sap> field is the service access point, and describes how to access the service. In addition, although both upper case and lower case characters are recognized in the <service- type> field for convenience, the name is case-folded into lower case. Service types are therefore not distinguished on the basis of case, so, for example, "http" and "HTTP" designate the same service type. This is consistent with general URL practice, as outlined in [5].

The ABNF for a service: URL is:

service: URL = "service:" service-type ":" sap service-type = abstract-type ":" url-scheme / concrete-type abstract-type = type-name [ "." naming-auth ] concrete-type = protocol [ "." naming-auth ] type-name = resname naming-auth = resname url-scheme = resname ; A recognized URL scheme name, standardized ; either through common practice or through ; approval of a standards body. resname = ALPHA [ 1*(ALPHA / DIGIT / "+" / "-") ] sap = site [url-part] site = ipsite / atsite / ipxsite ipsite = "//" [ [ user "@" ] hostport ] hostport = host [ ":" port ] host = hostname / hostnumber hostname = *( domainlabel "." ) toplabel alphanum = ALPHA / DIGIT domainlabel = alphanum / alphanum *[alphanum / "-"] alphanum toplabel = ALPHA / ALPHA *[ alphanum / "-" ] alphanum hostnumber = ipv4-number ipv4-number = 1*3DIGIT 3("." 1*3DIGIT) port = 1*DIGIT ; A port number must be included if the ; protocol field does not have an IANA ; assigned port number. user = *[ uchar / ";" / "+" / "&" / "=" ] ipxsite = "/ipx/" ipx-net ":" ipx-node ":" ipx-socket ipx-net = 8 HEXDIGIT ipx-node = 12 HEXDIGIT ipx-socket = 4 HEXDIGIT atsite = "/at/" at-object ":" at-type "" at-zone at-object = 1*31apple-char at-type = 1*31apple-char at-zone = 1*31apple-char apple-char = ALPHA / DIGIT / safe / escaped = ; AppleAscii [7] values that are not = ; from the restricted range must be escaped. = ; NOTE: The escaped values do NOT correspond = ; to UTF-8 values here: They are AppleAscii = ; bytes. url-part = [ url-path ] [ attr-list ] url-path = 1 * ( "/" *xchar ) ; Each service type must define its ; own syntax consistent ; with [5]. attr-list = 1 * ( ";" attr-asgn ) attr-asgn = attr-id / attr-id "=" attr-value safe = "$" / "-" / "_" / "." / "~" extra = "!" / "*" / "'" / "(" / ")" / "," / "+" uchar = unreserved / escaped xchar = unreserved / reserved / escaped escaped = 1*(`\' HEXDIG HEXDIG) reserved = "; "?" / ":" / "@" / "&" / "=" / "+" unreserved = ALPHA / DIGIT / safe / extra

IPX addresses [14] are composed of a network, node and socket number. The IPX network number is a four-byte number, in network order and expressed in hexadecimal, that signifies an IPX subnet. The node element represents a network interface card. It is a six-byte number, expressed in hexadecimal, that is usually the same as the node ID of the interface card. The socket element represents a specific service access point, given an IPX network and node. IPX sockets are analogous to TCP/IP ports, and are not to be confused with Berkeley sockets.

AppleTalk addresses [9] are composed of an object, type and zone. The object is a human readable string. The type is an identifier, not intended for human readability. The zone refers to the AppleTalk Zone name, which is also human readable. The characters composing these names are drawn from the AppleAscii character set [7]. Thus, they do not equate to escaped ASCII or UTF-8 characters. The characters "=" and "*" are reserved and may not be included in the names even in binary form.

In cases besides the AppleTalk grammar, some characters must be escaped before use. To escape any character, precede the two digits indicating its ASCII value by '%'.

Service URL Semantics

The service scheme-specific information following the "service:" URL scheme identifier provides information necessary to access the service. As described in the previous subsection, the form of a service: URL is as follows:

    service: URL = "service:" service-type ":" site url-path

where <site> has one of the following forms could refer to an <ipsite>, <ipxsite> or <atsite> if the service URL locates to an IP, IPX or AppleTalk service access point, respectively.

As discussed in Section 1, the <service-type> can be either a concrete protocol name, or an abstract type name.

The <ipsite> field is typically either a domain name (DNS) or an IP network protocol address for the service, and possibly a port number. Note that use of DNS hostnames is preferred for ease of renumbering. The <site> field can be null if other information in the service URL or service attributes is sufficient to use the service.

The <sap> field allows more information to be provided (by way of <url-path> and <attr-list>) that can uniquely locate the service or resource if the <site> is not sufficient for that purpose. For IP addresses, the <site> field begins with "//". Other address families supported are IPX [14] and AppleTalk [9].

An <attr-list> field appears at the end of the <url-part> field, but is never required to exist in any service location registration.

The <attr-list> field is composed of a list of semicolon (";") separated attribute assignments of the form:

    attr-id "=" attr-value

or for keyword attributes:

    attr-id

Attributes are part of service: URLs when the attributes are required to access a particular service. For instance, an ACAP [13] service might require that the client authenticate with it through Kerberos. Including an attribute in the service registration allows the ACAP client to make use of the correct SASL [11] authentication mechanism. The ACAP server's registration might look like:

    service:acap://some.where.net;authentication=KERBEROSV4

Note that there can be other attributes of an ACAP server which are not appropriate to include in the URL. For instance, the list of users who have access to the server is useful for selecting an ACAP server, but is not required for a client to use the registered service.

Attributes associated with the service: URL are not typically included in the service: URL. They are stored and retrieved using other mechanisms. The service: URL is uniquely identified with a particular service agent or resource, and is used when registering or requesting the attribute information. The Service Location Protocol specifies how such information is registered by network services and obtained by client software.


Constructor Summary
ServiceUrl(java.lang.String specification)
          Constructs a ServiceUrl object from the specified String
ServiceUrl(java.lang.String serviceType, java.net.InetAddress address, java.lang.Integer port, java.util.List attributes)
          Constructs a ServiceUrl object
ServiceUrl(java.lang.String concreteType, java.lang.String namingAuthority, java.net.InetAddress address, java.lang.Integer port, java.util.List attributes)
          Constructs a ServiceUrl object
ServiceUrl(java.lang.String abstractType, java.lang.String namingAuthority, java.lang.String concreteType, java.net.InetAddress address, java.lang.Integer port, java.util.List attributes)
          Constructs a ServiceUrl object
 
Method Summary
 java.lang.Object clone()
           
 java.lang.String getAbstractType()
          Returns abstract type
 java.net.InetAddress getAddress()
          Returns address
 java.util.List getAttributes()
          Returns service attributes
 java.lang.String getConcreteType()
          Returns concrete type
 java.lang.String getNamingAuthority()
          Returns naming authority
 int getPort()
          Returns port
 java.lang.String getServiceType()
          Returns service type
 java.lang.String getUrl()
          Returns url
 java.lang.String getUrlScheme()
          Returns url scheme
 java.lang.String toString()
          Returns a string representation of the object.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ServiceUrl

public ServiceUrl(java.lang.String specification)
           throws java.net.MalformedURLException
Constructs a ServiceUrl object from the specified String

Parameters:
specification - the String to parse as a service url
Throws:
java.lang.NullPointerException - if specification is null
java.net.MalformedURLException - if the string specifies an unknown protocol

ServiceUrl

public ServiceUrl(java.lang.String abstractType,
                  java.lang.String namingAuthority,
                  java.lang.String concreteType,
                  java.net.InetAddress address,
                  java.lang.Integer port,
                  java.util.List attributes)
           throws java.net.MalformedURLException
Constructs a ServiceUrl object

Parameters:
abstractType - abstract type
namingAuthority - naming authority or null for IANA
concreteType - concrete type
address - internet address
port - port or null for default port
Throws:
java.lang.NullPointerException - if abstractType, concreteType, or address are null
java.net.MalformedURLException - if the parameters do not specify a valid service url

ServiceUrl

public ServiceUrl(java.lang.String concreteType,
                  java.lang.String namingAuthority,
                  java.net.InetAddress address,
                  java.lang.Integer port,
                  java.util.List attributes)
           throws java.net.MalformedURLException
Constructs a ServiceUrl object

Parameters:
concreteType - concrete type
namingAuthority - naming authority or null for IANA
address - internet address
port - port or null for default port
Throws:
java.lang.NullPointerException - if concreteType or address are null
java.net.MalformedURLException - if the parameters do not specify a valid service url

ServiceUrl

public ServiceUrl(java.lang.String serviceType,
                  java.net.InetAddress address,
                  java.lang.Integer port,
                  java.util.List attributes)
           throws java.net.MalformedURLException
Constructs a ServiceUrl object

Parameters:
serviceType - service type (including "service:" prefix)
address - internet address
port - port or null for default port
Throws:
java.lang.NullPointerException - if serviceType or address are null
java.net.MalformedURLException - if the parameters do not specify a valid service url
Method Detail

getUrl

public java.lang.String getUrl()
Returns url

Returns:
String service url

getServiceType

public java.lang.String getServiceType()
Returns service type

Returns:
String service type

getAbstractType

public java.lang.String getAbstractType()
Returns abstract type

Returns:
String abstract type or null

getUrlScheme

public java.lang.String getUrlScheme()
Returns url scheme

Returns:
String url scheme

getConcreteType

public java.lang.String getConcreteType()
Returns concrete type

Returns:
String concreate type

getNamingAuthority

public java.lang.String getNamingAuthority()
Returns naming authority

Returns:
String naming authority or null (IANA)

getAddress

public java.net.InetAddress getAddress()
Returns address

Returns:
InetAddress address

getPort

public int getPort()
Returns port

Returns:
int port or -1 for default port

getAttributes

public java.util.List getAttributes()
Returns service attributes

Returns:
List service attributes (Attribute objects)

clone

public final java.lang.Object clone()
                             throws java.lang.CloneNotSupportedException
Throws:
java.lang.CloneNotSupportedException
See Also:
Object.clone()

toString

public java.lang.String toString()
Returns a string representation of the object.

See Also:
Object.toString()