org.xins.common.service

Class TargetDescriptor

java.lang.Object

org.xins.common.service.Descriptor

org.xins.common.service.TargetDescriptor

All Implemented Interfaces:

Serializable, Iterable<TargetDescriptor>

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.70 $ $Date: 2012/03/03 21:23:44 $

Author:

Ernst de Haan

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
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

Methods

Modifier and Type	Method and Description
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.
Iterator<TargetDescriptor>	iterator()
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.

iterator

public Iterator<TargetDescriptor> iterator()

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.

Overrides:

hashCode in class 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

Overrides:

equals in class Object

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)

Overrides:

toString in class Object

Returns:

this TargetDescriptor as a String, never null.