de.fhg.igd.semoa.net.ship
Interface ShipService

All Superinterfaces:

ShipConstants

All Known Implementing Classes:

ShipServer

public interface ShipService

extends ShipConstants

SHIP (simple host information protocols) provides information on remote SeMoA hosts. The query is based on key-value pairs which are defined by each host. A local component (e.g. an agent or service) may ask for

• a certain value of a given key,
• the whole set of key, and
• the whole map of key-value pairs

on a distinct host.

This service should not be accessible only to trust-worthy agents, since SHIP could be misused for denial-of-service (DoS) or even distributed denial-of-service (DDoS) attacks. You really should ensure this fact in SeMoA's security policy.

Each method has a remote and a local version. The local version queries the actual host and (surprise, surprise) miss a parameter URL host. The methods for local retrieval do not rely on a network infrastructure since the results will be gained by internal method calls only .

Some of the methods allow wildcards. They are interpreted according to Java regular expressions defined in the package java.util.regex. There are a number of well-known keys that sould be used for SHIP within a SeMoA server. They are defined as follows:

Version:

"$Id: ShipService.java 1913 2007-08-08 02:41:53Z jpeters $"

Author:

Ulrich Pinsdorf, Patric Kabus

Field Summary

static String

WHATIS The WhatIs entry key for this service.

Fields inherited from interface de.fhg.igd.semoa.net.ship.ShipConstants

COMM_POD_ACL, COMM_POD_URL, COMM_PODS_ACL, COMM_PODS_URL, LOCATION_ADDRESS, LOCATION_CITY, LOCATION_COUNTRY, LOCATION_GPS_LAT, LOCATION_GPS_LONG, LOCATION_ROOM, LOCATION_STATE, LOCATION_ZIP, OWNER_DN, PLATFORM_PURPOSE, TRANSPORT_IN_RAW_MAX, TRANSPORT_IN_RAW_URL, TRANSPORT_IN_RAWS_MAX, TRANSPORT_IN_RAWS_URL

Method Summary

Set	getKeySet() Returns a set of all SHIP keys defined by the local SHIP service.
Set	getKeySet(String expr) Returns a subset of SHIP keys defined by the local SHIP service.
Set	getKeySet(String expr, URL host) Returns a subset of SHIP keys defined by a remote SHIP service.
Set	getKeySet(URL host) Returns a set of all SHIP keys defined by a remote SHIP service.
Map	getMap() Returns the complete map of key value pairs defined by the local SHIP service.
Map	getMap(String expr) Returns a subset of key value pairs defined by the local SHIP service.
Map	getMap(String expr, URL host) Returns the a subset of key value pairs by a remote SHIP service.
Map	getMap(URL host) Returns the complete map of key value pairs by a remote SHIP service.
String	getValue(String key) Returns a specific value selected by a given key defined by the local SHIP service.
String	getValue(String key, URL host) Returns a specific value selected by a given key defined by on a remote SHIP service.
boolean	isAlive(URL host) Checks whether a certain host is alive.
String	localDN()
URL	localURL()

Field Detail

WHATIS

public static final String WHATIS

The WhatIs entry key for this service.

See Also:

Constant Field Values

Method Detail

isAlive

public boolean isAlive(URL host)
                throws ShipException

Checks whether a certain host is alive. Within a LAN this is the job of vicinity. This method is intended to be used with somewhat far hosts. This method a specified time for an answer from the remote host. Iff no result was received or an error occured during pinging the method returns with result false. Hence, a negative result may not be interpreted as if the pinged host is down; the server could just deny answering SHIP requests.

Parameters:

host - denotes the SHIP port of the host to be queried

Returns:

true if host is alive

Throws:

ShipException - if access connection to remote SHIP service fails.

SecurityException - if caller has not the proper permission to invoke lookups

getKeySet

public Set getKeySet(String expr,
                     URL host)
              throws ShipException

Returns a subset of SHIP keys defined by a remote SHIP service.

Parameters:

expr - allows wildcards to get just a subset of the map

host - denotes denotes the SHIP port of the host to be queried

Returns:

set of all keys defined at remote host's ship service

Throws:

ShipException - if access connection to remote SHIP service fails.

SecurityException - if caller has not the proper permission to invoke lookups

getKeySet

public Set getKeySet(String expr)

Returns a subset of SHIP keys defined by the local SHIP service.

Parameters:

expr - allows wildcards to get just a subset of the map

Returns:

set of all keys defined at remote host's ship service

Throws:

SecurityException - if caller has not the proper permission to invoke lookups

getKeySet

public Set getKeySet(URL host)
              throws ShipException

Returns a set of all SHIP keys defined by a remote SHIP service.

Parameters:

host - denotes denotes the SHIP port of the host to be queried

Returns:

set of all keys defined at remote host's ship service

Throws:

ShipException - if access connection to remote SHIP service fails.

SecurityException - if caller has not the proper permission to invoke lookups

getKeySet

public Set getKeySet()

Returns a set of all SHIP keys defined by the local SHIP service.

Returns:

set of all keys defined at remote host's ship service

Throws:

SecurityException - if caller has not the proper permission to invoke lookups

getValue

public String getValue(String key,
                       URL host)
                throws ShipException

Returns a specific value selected by a given key defined by on a remote SHIP service.

Parameters:

key - defines a specific value

host - denotes the SHIP port of the host to be queried

Returns:

the value according to the given key, if key is existent.

Throws:

ShipException - if access connection to remote SHIP service fails.

SecurityException - if caller has not the proper permission to invoke lookups

getValue

public String getValue(String key)

Returns a specific value selected by a given key defined by the local SHIP service.

Parameters:

key - defines a specific value

Returns:

the value according to the given key, if key is existent, null otherwise.

Throws:

SecurityException - if caller has not the proper permission to invoke lookups

getMap

public Map getMap(String expr,
                  URL host)
           throws ShipException

Returns the a subset of key value pairs by a remote SHIP service.

Parameters:

expr - allows wildcards to get just a subset of the map

host - denotes the SHIP port of the host to be queried

Returns:

set of all keys defined at remote host's ship service

Throws:

ShipException - if access connection to remote SHIP service fails.

SecurityException - if caller has not the proper permission to invoke lookups

getMap

public Map getMap(String expr)

Returns a subset of key value pairs defined by the local SHIP service.

Parameters:

expr - allows wildcards to get just a subset of the map

Returns:

set of all keys defined at remote host's ship service

Throws:

SecurityException - if caller has not the proper permission to invoke lookups

getMap

public Map getMap(URL host)
           throws ShipException

Returns the complete map of key value pairs by a remote SHIP service. The method calls getMap(".*", host).

Parameters:

host - denotes the SHIP port of the host to be queried

Returns:

set of all keys defined at remote host's ship service

Throws:

ShipException - if access connection to remote SHIP service fails.

SecurityException - if caller has not the proper permission to invoke lookups

getMap

public Map getMap()

Returns the complete map of key value pairs defined by the local SHIP service. Calls getMap(".*")

Returns:

set of all keys defined at remote host's ship service

Throws:

SecurityException - if caller has not the proper permission to invoke lookups

localURL

public URL localURL()

Returns:

The URL that specifies the host (interface), port, and protocol of this server. Please note that the URL class returned is not java.net.URL.

localDN

public String localDN()

Returns:

The distinguished name that specifies the owner of the host by means of the owner's certificate subject as String (see KeyMaster.AUTH_KEY).