Generated: Wed Apr 20 14:41:06 BST 2005

org.bionanny.shared
Interface Bionanny


public interface Bionanny

An interface defining access to a monitoring service. The main purpose is to monitor how many requests were done and how much time they took.

The requests are mainly assumed to be identical to the Web Services operations (that was the original idea behind this small project). Therefore and even though, most implementations of this interface aim to Web Services, there is nothing to prevent to use this interface and to implement it for monitoring other things (such as a usual Java method profiling).

In oder to be able to implement smoothly a monitoring service itself as a web service, this interface uses only limited data structures, and if even them are too complex for some client programming languages, it also allows to receive monitored data as XML strings.

The terminology used in this interface starts with a service which is represented (usually) by a Web Service (but it can be any entity that is supposed to be monitored). Then each service consists of one or more requests. A request is (aain, usually) represented by one call from a client to this Web Service. It corresponds with a SOAP operation.

Version:
$Id: Bionanny.java,v 1.1.1.1 2005/04/19 14:49:48 marsenger Exp $
Author:
Martin Senger, Mike Niemi

Field Summary
static int CUMULATED_FOR_REQUESTS
          A level indicating that the returned date should be cumulated on a request level.
static int CUMULATED_FOR_SERVICES
          A level indicating that the returned date should be cumulated on a service level.
static java.lang.String DATA_INPUT_LENGTH
          A name used to identify metadata.
static java.lang.String DATA_OUTPUT_LENGTH
          A name used to identify metadata.
static java.lang.String NAME_DELIMITER
          A string serving as a delimiter when both a unique name and a display name are returned.
static int NOT_CUMULATED
          A level indicating that the returned date should not be cumulated at all.
static int ONLY_RUNNING_SERVICES
          A value used in 'periodFrom' and 'periodTo' in the get(int, java.lang.String[], long, long, java.lang.String[]) method to indicate that only records about still running services should be selected.
 
Method Summary
 java.lang.String[] availableAllMetadata()
          Return a list of names of all available metadata, disregarding which service they were registered for.
 java.lang.String[] availableMetadata(java.lang.String serviceName)
          Return a list of names of metadata available for given service.
 java.lang.String[] availableServices()
          Return a list of names of services this monitoring service has some data about.
 CollectedData[] get(int level, java.lang.String[] serviceNames, long periodFrom, long periodTo, java.lang.String[] metadataNames)
          Return data that had been logged here by the log method.
 java.lang.String getAsXML(int level, java.lang.String[] serviceNames, long periodFrom, long periodTo, java.lang.String[] metadataNames)
           
 void log(java.lang.String serviceEndpoint, java.lang.String serviceName, java.lang.String requestId, java.lang.String recordId, java.lang.String sender, long startedAt, long elapsedTime, Metadata[] metadata)
          Report (log) run-time information to a monitoring service.
 

Field Detail

DATA_INPUT_LENGTH

public static final java.lang.String DATA_INPUT_LENGTH
A name used to identify metadata. The value stored under this name contains amount of input data (in bytes) that were processed by a web service.

See Also:
Constant Field Values

DATA_OUTPUT_LENGTH

public static final java.lang.String DATA_OUTPUT_LENGTH
A name used to identify metadata. The value stored under this name contains amount of resulting data (in bytes) that were produced by a web service.

See Also:
Constant Field Values

NOT_CUMULATED

public static final int NOT_CUMULATED
A level indicating that the returned date should not be cumulated at all.

See Also:
get, Constant Field Values

CUMULATED_FOR_SERVICES

public static final int CUMULATED_FOR_SERVICES
A level indicating that the returned date should be cumulated on a service level.

See Also:
get, Constant Field Values

CUMULATED_FOR_REQUESTS

public static final int CUMULATED_FOR_REQUESTS
A level indicating that the returned date should be cumulated on a request level.

See Also:
get, Constant Field Values

ONLY_RUNNING_SERVICES

public static final int ONLY_RUNNING_SERVICES
A value used in 'periodFrom' and 'periodTo' in the get(int, java.lang.String[], long, long, java.lang.String[]) method to indicate that only records about still running services should be selected.

See Also:
Constant Field Values

NAME_DELIMITER

public static final java.lang.String NAME_DELIMITER
A string serving as a delimiter when both a unique name and a display name are returned.

See Also:
availableServices, Constant Field Values
Method Detail

log

public void log(java.lang.String serviceEndpoint,
                java.lang.String serviceName,
                java.lang.String requestId,
                java.lang.String recordId,
                java.lang.String sender,
                long startedAt,
                long elapsedTime,
                Metadata[] metadata)
         throws BionannyException
Report (log) run-time information to a monitoring service.

Parameters:
serviceEndpoint - is a unique identifier for a service who makes the report
serviceName - is a name of the same service; it must be unique within 'serviceEndpoint' (meaning: two services with two different endpoints may have the same service name); it has meaning as a "display name", nothing else; if you use two different service names within the same serviceEndpoint, there is no guarantee that both will be remembered
requestId - is a unique identifier within a 'serviceEndpoint', specifying the request (usually it means a name of the requested operation); it may be empty
recordId - is a unique identifier of this logging call (within serviceEndpoint and requestId). It is supposed to be used only in cases that the current logged information is not complete and there will be later another 'log' call to complete the same event. The 'recordId' is here to pair (match) the two calls together.

The semantics of the next call is to replace everything what is the new call but keep things that were recorded by the first call and are empty in the second one. The implementation is allowed (for the optimalization reasons) to keep the unfinished records only until the second call.

Note that this information is not available in the otherwise symmetric get(int, java.lang.String[], long, long, java.lang.String[]) method.

sender - identifies who is making this request; it may be empty

startedAt - in milliseconds, when the logged event started. This can be empty - in which case the implementation uses the current time of recording. This is meant mainly for cases when the same event is logged twice (see parameter 'recordId' above) - once at its beginning and once when it ends. In such cases may be important to say what was the exact start of the even because the current time may not be good enough, especially when the logging is done over the network, on a different machine.

elapsedTime - in milliseconds how long took to fulfill this request (or service if the requestId is empty)

metadata - is a set of name/value pairs specifying additional data related to this request, or service; some common names are defined in this interface
Throws:
BionannyException

get

public CollectedData[] get(int level,
                           java.lang.String[] serviceNames,
                           long periodFrom,
                           long periodTo,
                           java.lang.String[] metadataNames)
                    throws BionannyException
Return data that had been logged here by the log method. The returned data can be cumulated on the requested level. Data can also be selected in order to contain any combination of:

Parameters:
level - of cumulation, can be one of: NOT_CUMULATED, CUMULATED_FOR_SERVICES, CUMULATED_FOR_REQUESTS
serviceNames - is a list of services whose data should be returned; the available service names can be obtained by the availableServices() method; if empty then data for all available services are returned
periodFrom - in millisecond from the beginning of Epoch (1.1.1970), expressed in GMT, specifies a starting point of interval the data will be returned for; a negative value means relative period backwards from now; zero means that this parameter is not specified; a special value is ONLY_RUNNING_SERVICES - when both 'periodFrom' and 'periodTo' are set to this value (which is a very small number that is unlikely to collide with a real period) then the method returns only services that has been started but has , but possitive, not yet finished
periodTo - in millisecond from the beginning of Epoch (1.1.1970), expressed in GMT, specifies an ending point of interval the data will be returned for; a negative value means relative period from now; zero means that this parameter is not specified; see also 'periodFrom' about a special value ONLY_RUNNING_SERVICES
metadataNames - can limit what metadata should be returned
Returns:
raw or cumulated data (TBD: better)
Throws:
BionannyException

getAsXML

public java.lang.String getAsXML(int level,
                                 java.lang.String[] serviceNames,
                                 long periodFrom,
                                 long periodTo,
                                 java.lang.String[] metadataNames)
                          throws BionannyException
Throws:
BionannyException

availableServices

public java.lang.String[] availableServices()
                                     throws BionannyException
Return a list of names of services this monitoring service has some data about.

Returns:
a list of names; each name consists of a service endpoint and a service display name, separated by a NAME_DELIMITER
Throws:
BionannyException

availableMetadata

public java.lang.String[] availableMetadata(java.lang.String serviceName)
                                     throws BionannyException
Return a list of names of metadata available for given service.

Parameters:
serviceName - is one of names returned by availableServices
Returns:
list of names of existing/recorded metadata for given 'serviceName', or an empty array if there are no metadata for given service, or null if the given service name does not exist
Throws:
BionannyException

availableAllMetadata

public java.lang.String[] availableAllMetadata()
                                        throws BionannyException
Return a list of names of all available metadata, disregarding which service they were registered for.

Returns:
list of names of existing/recorded metadata, or an empty array if there are no metadata at all
Throws:
BionannyException

Generated: Wed Apr 20 14:41:06 BST 2005

Submit a bug or feature
Generated: Wed Apr 20 14:41:06 BST 2005