org.xins.common.service
Class TargetDescriptor

java.lang.Object
  org.xins.common.service.Descriptor
      org.xins.common.service.TargetDescriptor

All Implemented Interfaces:

Serializable

public final class TargetDescriptor

extends Descriptor

Descriptor for a single target service. A target descriptor defines a URL that identifies the location of the service. Also, it may define 3 kinds of time-outs:

total time-out (getTotalTimeOut())

the maximum duration of a call, including connection time, time used to send the request, time used to receive the response, etc.

connection time-out (getConnectionTimeOut())

the maximum time for attempting to establish a connection.

socket time-out (getSocketTimeOut())

the maximum time for attempting to receive data on a socket.

Since:

XINS 1.0.0

Version:

$Revision: 1.47 $ $Date: 2006/08/28 09:12:34 $

Author:

Ernst de Haan

See Also:

Serialized Form

Constructor Summary

TargetDescriptor(String url)
Constructs a new TargetDescriptor for the specified URL.

TargetDescriptor(String url, int timeOut)
Constructs a new TargetDescriptor for the specified URL, with the specifed total time-out.

TargetDescriptor(String url, int timeOut, int connectionTimeOut)
Constructs a new TargetDescriptor for the specified URL, with the specifed total time-out and connection time-out.

TargetDescriptor(String url, int timeOut, int connectionTimeOut, int socketTimeOut)
Constructs a new TargetDescriptor for the specified URL, with the specifed total time-out, connection time-out and socket time-out.

Method Summary

boolean	equals(Object obj) Indicates whether some other object is "equal to" this one.
int	getConnectionTimeOut() Returns the connection time-out for a call to the service.
int	getCRC() Returns the CRC-32 checksum for the URL of this target descriptor.
String	getProtocol() Returns the protocol in the URL for the service.
int	getSocketTimeOut() Returns the socket time-out for a call to the service.
TargetDescriptor	getTargetByCRC(int crc) Returns the TargetDescriptor that matches the specified CRC-32 checksum.
int	getTargetCount() Counts the total number of target descriptors in/under this descriptor.
int	getTotalTimeOut() Returns the total time-out for a call to the service.
String	getURL() Returns the URL for the service.
int	hashCode() Returns a hash code value for the object.
boolean	isGroup() Checks if this descriptor denotes a group of descriptors.
Iterator	iterateTargets() Iterates over all leaves, the target descriptors.
String	toString() Textual description of this object.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

TargetDescriptor

public TargetDescriptor(String url)
                 throws IllegalArgumentException,
                        MalformedURLException

Constructs a new TargetDescriptor for the specified URL.

Note: Both the connection time-out and the socket time-out will be set to the default time-out: 5 seconds.

Parameters:

url - the URL of the service, cannot be null.

Throws:

IllegalArgumentException - if url == null.

MalformedURLException - if the specified URL is malformed.

TargetDescriptor

public TargetDescriptor(String url,
                        int timeOut)
                 throws IllegalArgumentException,
                        MalformedURLException

Constructs a new TargetDescriptor for the specified URL, with the specifed total time-out.

Note: Both the connection time-out and the socket time-out will be set to equal the total time-out.

Parameters:

url - the URL of the service, cannot be null.

timeOut - the total time-out for the service, in milliseconds; or a non-positive value for no total time-out.

Throws:

IllegalArgumentException - if url == null.

MalformedURLException - if the specified URL is malformed.

TargetDescriptor

public TargetDescriptor(String url,
                        int timeOut,
                        int connectionTimeOut)
                 throws IllegalArgumentException,
                        MalformedURLException

Constructs a new TargetDescriptor for the specified URL, with the specifed total time-out and connection time-out.

Note: If the passed connection time-out is smaller than 1 ms, or greater than the total time-out, then it will be adjusted to equal the total time-out.

Note: The socket time-out will be set to equal the total time-out.

Parameters:

url - the URL of the service, cannot be null.

timeOut - the total time-out for the service, in milliseconds; or a non-positive value for no total time-out.

connectionTimeOut - the connection time-out for the service, in milliseconds; or a non-positive value if the connection time-out should equal the total time-out.

Throws:

IllegalArgumentException - if url == null.

MalformedURLException - if the specified URL is malformed.

TargetDescriptor

public TargetDescriptor(String url,
                        int timeOut,
                        int connectionTimeOut,
                        int socketTimeOut)
                 throws IllegalArgumentException,
                        MalformedURLException

Constructs a new TargetDescriptor for the specified URL, with the specifed total time-out, connection time-out and socket time-out.

Note: If the passed connection time-out is smaller than 1 ms, or greater than the total time-out, then it will be adjusted to equal the total time-out.

Note: If the passed socket time-out is smaller than 1 ms or greater than the total time-out, then it will be adjusted to equal the total time-out.

Parameters:

url - the URL of the service, cannot be null.

timeOut - the total time-out for the service, in milliseconds; or a non-positive value for no total time-out.

connectionTimeOut - the connection time-out for the service, in milliseconds; or a non-positive value if the connection time-out should equal the total time-out.

socketTimeOut - the socket time-out for the service, in milliseconds; or a non-positive value for no socket time-out.

Throws:

IllegalArgumentException - if url == null.

MalformedURLException - if the specified URL is malformed.

Method Detail

isGroup

public boolean isGroup()

Checks if this descriptor denotes a group of descriptors.

Specified by:

isGroup in class Descriptor

Returns:

false, since this descriptor does not denote a group.

getURL

public String getURL()

Returns the URL for the service.

Returns:

the URL for the service, not null.

getProtocol

public String getProtocol()

Returns the protocol in the URL for the service.

Returns:

the protocol in the URL, not null.

Since:

XINS 1.2.0

getTotalTimeOut

public int getTotalTimeOut()

Returns the total time-out for a call to the service. The value 0 is returned if there is no total time-out.

Returns:

the total time-out for the service, as a positive number, in milli-seconds, or 0 if there is no total time-out.

getConnectionTimeOut

public int getConnectionTimeOut()

Returns the connection time-out for a call to the service.

Returns:

the connection time-out for the service; always greater than 0 and smaller than or equal to the total time-out.

getSocketTimeOut

public int getSocketTimeOut()

Returns the socket time-out for a call to the service.

Returns:

the socket time-out for the service; always greater than 0 and smaller than or equal to the total time-out.

getCRC

public int getCRC()

Returns the CRC-32 checksum for the URL of this target descriptor.

Returns:

the CRC-32 checksum.

iterateTargets

public Iterator iterateTargets()

Iterates over all leaves, the target descriptors.

The returned Iterator will only return this target descriptor.

Specified by:

iterateTargets in class Descriptor

Returns:

iterator that returns this target descriptor, never null.

getTargetCount

public int getTargetCount()

Counts the total number of target descriptors in/under this descriptor.

Specified by:

getTargetCount in class Descriptor

Returns:

the total number of target descriptors, always 1.

getTargetByCRC

public TargetDescriptor getTargetByCRC(int crc)

Returns the TargetDescriptor that matches the specified CRC-32 checksum.

Specified by:

getTargetByCRC in class Descriptor

Parameters:

crc - the CRC-32 checksum.

Returns:

the TargetDescriptor that matches the specified checksum, or null, if none could be found in this descriptor.

hashCode

public int hashCode()

Returns a hash code value for the object.

Returns:

a hash code value for this object.

See Also:

Object.hashCode(), equals(Object)

equals

public boolean equals(Object obj)

Indicates whether some other object is "equal to" this one. This method considers obj equals if and only if it matches the following conditions:

• obj instanceof TargetDescriptor
• URL is equal
• total time-out is equal
• connection time-out is equal
• socket time-out is equal

Parameters:

obj - the reference object with which to compare.

Returns:

true if this object is the same as the obj argument; false otherwise.

See Also:

hashCode()

toString

public String toString()

Textual description of this object. The string includes the URL and all time-out values. For example:

TargetDescriptor(url="http://api.google.com/some_api/"; total-time-out is 5300 ms; connection time-out is 1000 ms; socket time-out is disabled)

Returns:

this TargetDescriptor as a String, never null.