org.ws4d.java.service
Interface Service

All Known Subinterfaces:
LocalService
All Known Implementing Classes:
DefaultService, ProxyService, ServiceCommons

public interface Service

Interface of service classes representing "DPWS Hosted Services"


Method Summary
 EventSource getAnyEventSource(QName portType, java.lang.String eventName)
          Returns the first (or last, or ANY other) event source with the specified portType and eventName.
 Operation getAnyOperation(QName portType, java.lang.String operationName)
          Returns the first (or last, or ANY other) operation with the specified portType and operationName.
 java.lang.Object getCertificate()
          This certificate is used to validate signatures.
 WSDL getDescription(java.lang.String targetNamespace)
          Returns a WSDL document describing this service by the given namespace.
 Iterator getDescriptions()
          Returns an iterator over all WSDLs directly attached to this service.
 Iterator getEprInfos()
          Returns an iterator of EprInfo.
 EventSource getEventSource(QName portType, java.lang.String eventName, java.lang.String inputName, java.lang.String outputName)
          Gets event source of specified portType with given eventName.
 EventSource getEventSource(java.lang.String outputAction)
          Gets event source with specified unique outputAction.
 Iterator getEventSources()
          Gets all events sources.
 Iterator getEventSources(QName portType)
          Gets all event sources of the specified service port type.
 Operation getOperation(QName portType, java.lang.String opName, java.lang.String inputName, java.lang.String outputName)
          Gets an operation of specified portType with given opName.
 Operation getOperation(java.lang.String inputAction)
          Gets operation with specified unique inputAction.
 Iterator getOperations()
          Gets all operations.
 Iterator getOperations(QName portType)
          Gets all operations of the specified service port type.
 DeviceReference getParentDeviceReference()
          Gets device reference of parent device.
 CustomAttributeValue getPortTypeAttribute(QName portTypeName, QName attributeName)
          Returns the value of the port type attribute with the given name for the port type with the specified unique portTypeName or with null if this attribute is not available (or if its value is explicitly set to null).
 HashMap getPortTypeAttributes(QName portTypeName)
          Returns all port type attributes explicitly set on this service instance for the port type with the given unique portTypeName.
 Iterator getPortTypes()
          Gets service port types.
 URI getServiceId()
          Gets service id
 ServiceReference getServiceReference()
          Gets the service reference.
 long getStatus(ClientSubscription subscription)
          Returns the duration in milliseconds until expiration of the specified client subscription.
 boolean hasPortTypeAttributes(QName portTypeName)
          Returns true only if this service instance has at least one port type attribute set for the port type with the specified unique portTypeName.
 boolean isRemote()
          Is the service remote (proxy) or local?
 boolean isSecure()
          return weather or not a service uses the security techniques.
 long renew(ClientSubscription subscription, long duration)
          Renews an existing subscription with a new duration.
 void setCertificate(java.lang.Object cert)
          Sets the certificate of this service.
 void setSecure(boolean sec)
           
 ClientSubscription subscribe(EventSink sink, java.lang.String clientSubscriptionId, URISet eventActionURIs, long duration)
          Initializes event receiving from specified event sender.
 void unsubscribe(ClientSubscription subscription)
          Unsubscribe specified subscription.
 

Method Detail

getServiceId

URI getServiceId()
Gets service id

Returns:
service id

getEprInfos

Iterator getEprInfos()
Returns an iterator of EprInfo.

Returns:
an iterator of EprInfo.

getPortTypes

Iterator getPortTypes()
Gets service port types.

Returns:
service port types, data structure is read only.

getServiceReference

ServiceReference getServiceReference()
Gets the service reference.

Returns:
service reference

getParentDeviceReference

DeviceReference getParentDeviceReference()
Gets device reference of parent device. This method may return null in case this service doesn't reside on a device or its underlying device is not known at this time.

Returns:
device reference of parent device, may be null

getOperations

Iterator getOperations(QName portType)
Gets all operations of the specified service port type.

Parameters:
portType - specific port type
Returns:
the operations belonging to the specified port type

getOperations

Iterator getOperations()
Gets all operations.

Returns:
all operations

getOperation

Operation getOperation(QName portType,
                       java.lang.String opName,
                       java.lang.String inputName,
                       java.lang.String outputName)
Gets an operation of specified portType with given opName. The inputName and/or outputName may be null only if the requested operation doesn't have any input/output. Otherwise, this method won't get any results.

When an operation is added to a service, and it doesn't provide an explicit name for either its input or output elements (see OperationCommons.setInputName(String) and OperationCommons.setOutputName(String)), a default name is generated according to the WSDL 1.1 Specification. As long as there are other operations with the same input/output name which have already been added to this service, an incremental index is appended to the default generated name.

If you are certain that the operation of the specified portType and with the given opName is NOT overloaded (i.e. there is no other operation within the same port type with the same operation name), then you can use method getAnyOperation(QName, String) instead of this one.

Parameters:
portType - specific port type of operation
opName - name of operation
inputName - the name of the input element which belongs to this operation according to its WSDL; must be null, if operation has no input
outputName - the name of the output element which belongs to this operation according to its WSDL; must be null, if operation has no output
Returns:
requested operation or null, if not found
See Also:
getAnyOperation(QName, String)

getOperation

Operation getOperation(java.lang.String inputAction)
Gets operation with specified unique inputAction.

Parameters:
inputAction - the WS-Addressing action URI of the requested operation according to its WSDL
Returns:
requested operation or null, if not found

getAnyOperation

Operation getAnyOperation(QName portType,
                          java.lang.String operationName)
Returns the first (or last, or ANY other) operation with the specified portType and operationName. Note that there might be more than one operation with the same name and port type in the case of overloading. In such situations, it is the user's responsibility to determine which of the overloaded versions was returned by this method. This method returns null, if there are no operations matching the portType and operationName arguments.

This method is useful in case it is known that there is only one operation with a given name within a port type.

Parameters:
portType - the port type to which the desired operation
operationName - the name of the operation
Returns:
any (maybe randomly determined) operation with the given port type and name
See Also:
getOperation(QName, String, String, String)

getEventSources

Iterator getEventSources(QName portType)
Gets all event sources of the specified service port type.

Parameters:
portType - specific port type
Returns:
all event sources belonging to the specified service port type

getEventSources

Iterator getEventSources()
Gets all events sources.

Returns:
all event sources

getEventSource

EventSource getEventSource(QName portType,
                           java.lang.String eventName,
                           java.lang.String inputName,
                           java.lang.String outputName)
Gets event source of specified portType with given eventName. The inputName and/or outputName may be null only if the requested event source doesn't have any input/output. Otherwise, this method won't find any results. *

When an event source is added to a service, and it doesn't provide an explicit name for either its input or output elements (see OperationCommons.setInputName(String) and OperationCommons.setOutputName(String)), a default name is therefore generated according to the WSDL 1.1 Specification. If there are other event sources with the same input/output name already added to this service, an incremental index is appended to the default generated name.

If you are certain that the event source of the specified portType and with the given eventName is NOT overloaded (i.e. there is no other event source within the same port type with the same event name), then you can use method getAnyEventSource(QName, String) instead of this one.

Parameters:
portType - specific port type of operation
eventName - name of event source
inputName - the name of the input element that belongs to this event source according to its WSDL; must be null, if event source has no input
outputName - the name of the output element that belongs to this event source according to its WSDL; must be null, if event source has no output
Returns:
requested event source or null, if not found
See Also:
getAnyEventSource(QName, String)

getEventSource

EventSource getEventSource(java.lang.String outputAction)
Gets event source with specified unique outputAction.

Parameters:
outputAction - the WS-Addressing action URI of the requested event source according to its WSDL
Returns:
requested event or null if not found

getAnyEventSource

EventSource getAnyEventSource(QName portType,
                              java.lang.String eventName)
Returns the first (or last, or ANY other) event source with the specified portType and eventName. Note that there might be more than one event source with the same name and port type in the case of overloading. In such situations, it is the user's responsibility to determine which of the overloaded versions was returned by this method. This method returns null, if there are no event source matching the portType and eventName arguments.

This method is useful in case it is known that there is only one event source with a given name within a port type.

Parameters:
portType - the port type the desired event source belongs to
eventName - the name of the event source
Returns:
any (maybe randomly determined) event source with the given port type and name
See Also:
getEventSource(QName, String, String, String)

isRemote

boolean isRemote()
Is the service remote (proxy) or local?

Returns:
whether this is a remote service (proxy) or not

subscribe

ClientSubscription subscribe(EventSink sink,
                             java.lang.String clientSubscriptionId,
                             URISet eventActionURIs,
                             long duration)
                             throws EventingException,
                                    TimeoutException
Initializes event receiving from specified event sender.

Parameters:
sink - event sink which will receive the notifications.
clientSubscriptionId -
eventActionURIs - a set of action URIs to subscribe to
duration - duration in millis of subscription. If 0, subscription does not expire.
Returns:
subscription id (wse:identifier)
Throws:
EventingException
TimeoutException

unsubscribe

void unsubscribe(ClientSubscription subscription)
                 throws EventingException,
                        TimeoutException
Unsubscribe specified subscription.

Parameters:
subscription - subscription to terminate.
Throws:
EventingException
TimeoutException

renew

long renew(ClientSubscription subscription,
           long duration)
           throws EventingException,
                  TimeoutException
Renews an existing subscription with a new duration. If duration is "0", subscription never terminates.

Parameters:
subscription -
duration -
Throws:
EventingException
TimeoutException

getStatus

long getStatus(ClientSubscription subscription)
               throws EventingException,
                      TimeoutException
Returns the duration in milliseconds until expiration of the specified client subscription.

Parameters:
subscription -
Returns:
Throws:
EventingException
TimeoutException

getDescriptions

Iterator getDescriptions()
Returns an iterator over all WSDLs directly attached to this service.

Returns:
an iterator over all WSDLs directly attached to this service

getDescription

WSDL getDescription(java.lang.String targetNamespace)
Returns a WSDL document describing this service by the given namespace. This method makes a recursive search within all WSDLs directly attached to that service.

Parameters:
targetNamespace - the namespace.
Returns:
the WSDL document describing this service by the given namespace.

getPortTypeAttribute

CustomAttributeValue getPortTypeAttribute(QName portTypeName,
                                          QName attributeName)
Returns the value of the port type attribute with the given name for the port type with the specified unique portTypeName or with null if this attribute is not available (or if its value is explicitly set to null).

This method throws a java.lang.IllegalArgumentException if a port type with the given portTypeName is not found within this service instance.

Parameters:
portTypeName - the unique name of the port type within the scope of this service instance, see getPortTypes()
attributeName - the name of the port type attribute to query the value of
Returns:
the value for the named port type attribute or null
Throws:
java.lang.IllegalArgumentException - if no port type with the given portTypeName is found

getPortTypeAttributes

HashMap getPortTypeAttributes(QName portTypeName)
Returns all port type attributes explicitly set on this service instance for the port type with the given unique portTypeName. Note that depending on the actual implementation the returned reference may point at the 'life map', i .e. the actual storage for the port type attributes. Thus, modifications to that map should be performed with care and keeping this in mind.

This method throws a java.lang.IllegalArgumentException if a port type with the given portTypeName is not found within this instance.

Parameters:
portTypeName - the unique name of the port type within the scope of this instance, see getPortTypes()
Returns:
all already set port type attributes
Throws:
java.lang.IllegalArgumentException - if no port type with the given portTypeName is found

hasPortTypeAttributes

boolean hasPortTypeAttributes(QName portTypeName)
Returns true only if this service instance has at least one port type attribute set for the port type with the specified unique portTypeName. Returns false in any other case, including when there is no port type with the given portTypeName.

Parameters:
portTypeName - the unique name of the port type within the scope of this service instance, see getPortTypes()
Returns:
true only if there is at least one port type attribute set for the named port type within this service instance

getCertificate

java.lang.Object getCertificate()
This certificate is used to validate signatures. Used in the security package.

Returns:
the java.security.cert.Certificate;

setCertificate

void setCertificate(java.lang.Object cert)
Sets the certificate of this service. Used only in the security package.

Parameters:
cert - the java.security.cert.Certificate

isSecure

boolean isSecure()
return weather or not a service uses the security techniques.

Returns:

setSecure

void setSecure(boolean sec)
Parameters:
sec -