org.cybergarage.upnp

## Class Service

- java.lang.Object
- - org.cybergarage.upnp.Service

-     public class Service
      extends Object

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `ELEM_NAME` XML element name for service nodes.
    `static String` | `MAJOR` XML element name for major version.
    `static String` | `MAJOR_VALUE` Default major version value.
    `static String` | `MINOR` XML element name for minor version.
    `static String` | `MINOR_VALUE` Default minor version value.
    `static String` | `SCPD_ROOTNODE` Root node name for service control point documents.
    `static String` | `SCPD_ROOTNODE_NS` Namespace for service control point documents.
    `static String` | `SPEC_VERSION` XML element name for specification version.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Service()` Creates a new empty Service instance.
    `Service(Node node)` Creates a Service instance from an existing XML node.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addAction(Action a)` Adds an action to this service.
    `void` | `addStateVariable(StateVariable var)` Add the StateVariable to the service. Note: This method should be used to create a dynamic Device withtout writing any XML that describe the device .
    `void` | `addSubscriber(Subscriber sub)`
    `void` | `announce(String bindAddr)` Announces this service to the network using SSDP.
    `void` | `byebye(String bindAddr)`
    `void` | `clearSID()`
    `Action` | `getAction(String actionName)` Finds an action by name in this service.
    `ActionList` | `getActionList()` Gets the list of actions provided by this service.
    `int` | `getConfigId()` Gets the configuration ID for this service.
    `String` | `getControlURL()` Gets the control URL for this service.
    `String` | `getDescriptionURL()` Gets the description URL for this service.
    `Device` | `getDevice()` Gets the device containing this service.
    `String` | `getEventSubURL()` Gets the event subscription URL for this service.
    `Device` | `getRootDevice()` Gets the root device containing this service.
    `byte[]` | `getSCPDData()` Gets the SCPD data for this service as a byte array.
    `String` | `getSCPDURL()` Gets the SCPD URL for this service.
    `String` | `getServiceID()` Gets the service ID of this service.
    `Node` | `getServiceNode()` Gets the XML node representing this service.
    `ServiceStateTable` | `getServiceStateTable()`
    `String` | `getServiceType()` Gets the service type of this service.
    `String` | `getSID()`
    `StateVariable` | `getStateVariable(String name)`
    `Subscriber` | `getSubscriber(String name)`
    `SubscriberList` | `getSubscriberList()`
    `long` | `getTimeout()`
    `Object` | `getUserData()`
    `boolean` | `hasSID()`
    `boolean` | `hasStateVariable(String name)`
    `boolean` | `isControlURL(String url)` Checks if the given URL matches this service's control URL.
    `boolean` | `isEventSubURL(String url)` Checks if the given URL matches this service's event subscription URL.
    `boolean` | `isSCPDURL(String url)` Checks if the given URL matches this service's SCPD URL.
    `boolean` | `isService(String name)`
    `static boolean` | `isServiceNode(Node node)` Checks if the given XML node represents a service.
    `boolean` | `isSubscribed()`
    `boolean` | `loadSCPD(File file)` Loads service control point description (SCPD) from a file.
    `boolean` | `loadSCPD(InputStream input)` Loads service description (SCPD) from an input stream.
    `boolean` | `loadSCPD(String scpdStr)` Loads service control point description (SCPD) from a string.
    `void` | `lock()` Acquires exclusive lock on this service for thread-safe operations.
    `void` | `notify(StateVariable stateVar)`
    `void` | `notifyAllStateVariables()`
    `void` | `removeSubscriber(Subscriber sub)`
    `boolean` | `serviceSearchResponse(SSDPPacket ssdpPacket)`
    `void` | `setActionListener(ActionListener listener)`
    `void` | `setControlURL(String value)` Sets the control URL for this service.
    `void` | `setDescriptionURL(String value)` Sets the description URL for this service.
    `void` | `setEventSubURL(String value)` Sets the event subscription URL for this service.
    `void` | `setQueryListener(QueryListener queryListener)`
    `void` | `setSCPDURL(String value)` Sets the SCPD URL for this service.
    `void` | `setServiceID(String value)` Sets service ID of this service.
    `void` | `setServiceType(String value)` Sets service type of this service.
    `void` | `setSID(String id)`
    `void` | `setTimeout(long value)`
    `void` | `setUserData(Object data)`
    `void` | `unlock()` Releases exclusive lock on this service.
    `void` | `updateConfigId()` Updates the configuration ID for this service based on its SCPD XML.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### ELEM_NAME

          public static final String ELEM_NAME

      XML element name for service nodes.
      See Also:
        Constant Field Values

    - #### MAJOR

          public static final String MAJOR

      XML element name for major version.
      See Also:
        Constant Field Values

    - #### MAJOR_VALUE

          public static final String MAJOR_VALUE

      Default major version value.
      See Also:
        Constant Field Values

    - #### MINOR

          public static final String MINOR

      XML element name for minor version.
      See Also:
        Constant Field Values

    - #### MINOR_VALUE

          public static final String MINOR_VALUE

      Default minor version value.
      See Also:
        Constant Field Values

    - #### SCPD_ROOTNODE

          public static final String SCPD_ROOTNODE

      Root node name for service control point documents.
      See Also:
        Constant Field Values

    - #### SCPD_ROOTNODE_NS

          public static final String SCPD_ROOTNODE_NS

      Namespace for service control point documents.
      See Also:
        Constant Field Values

    - #### SPEC_VERSION

          public static final String SPEC_VERSION

      XML element name for specification version.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Service

          public Service()

      Creates a new empty Service instance. This constructor creates a service with default SCPD specification version 1.0 and initializes the required XML structure.

    - #### Service

          public Service(Node node)

      Creates a Service instance from an existing XML node.
      Parameters:
        `node` - XML node representing the service

  - ### Method Detail

    - #### addAction

          public void addAction(Action a)

      Adds an action to this service.

      This method sets service reference for all arguments in action and adds action to the service's SCPD structure.

      Parameters:
        `a` - Action to add to this service

    - #### addStateVariable

          public void addStateVariable(StateVariable var)

      Add the StateVariable to the service.
      Note: This method should be used to create a dynamic
      Device withtout writing any XML that describe the device
      .
      Note: that no control for duplicate StateVariable is done.
      Parameters:
        `var` - StateVariable that will be added

    - #### addSubscriber

          public void addSubscriber(Subscriber sub)

    - #### announce

          public void announce(String bindAddr)

      Announces this service to the network using SSDP.

      This method sends SSDP NOTIFY messages to announce the service's presence. The announcement includes the service type, unique service identifier, and location of the root device containing this service.

      Parameters:
        `bindAddr` - bind address to send announcement from

    - #### byebye

          public void byebye(String bindAddr)

    - #### clearSID

          public void clearSID()

    - #### getAction

          public Action getAction(String actionName)

      Finds an action by name in this service.
      Parameters:
        `actionName` - name of action to find
      Returns:
        Action matching specified name, or null if not found

    - #### getActionList

          public ActionList getActionList()

      Gets the list of actions provided by this service.
      Returns:
        ActionList containing all actions of this service, empty list if no actions

    - #### getConfigId

          public int getConfigId()

      Gets the configuration ID for this service.
      Returns:
        the configuration ID, or 0 if not set

    - #### getControlURL

          public String getControlURL()

      Gets the control URL for this service.
      Returns:
        the control URL

    - #### getDescriptionURL

          public String getDescriptionURL()

      Gets the description URL for this service.
      Returns:
        the description URL

    - #### getDevice

          public Device getDevice()

      Gets the device containing this service.
      Returns:
        the parent device

    - #### getEventSubURL

          public String getEventSubURL()

      Gets the event subscription URL for this service.
      Returns:
        the event subscription URL

    - #### getRootDevice

          public Device getRootDevice()

      Gets the root device containing this service.
      Returns:
        the root device

    - #### getSCPDData

          public byte[] getSCPDData()

      Gets the SCPD data for this service as a byte array.
      Returns:
        the SCPD XML data as bytes, or empty array if not available

    - #### getSCPDURL

          public String getSCPDURL()

      Gets the SCPD URL for this service.
      Returns:
        the SCPD URL

    - #### getServiceID

          public String getServiceID()

      Gets the service ID of this service.
      Returns:
        service ID string, or empty string if not set

    - #### getServiceNode

          public Node getServiceNode()

      Gets the XML node representing this service.
      Returns:
        the service XML node

    - #### getServiceStateTable

          public ServiceStateTable getServiceStateTable()

    - #### getServiceType

          public String getServiceType()

      Gets the service type of this service.
      Returns:
        service type string, or empty string if not set

    - #### getSID

          public String getSID()

    - #### getStateVariable

          public StateVariable getStateVariable(String name)

    - #### getSubscriber

          public Subscriber getSubscriber(String name)

    - #### getSubscriberList

          public SubscriberList getSubscriberList()

    - #### getTimeout

          public long getTimeout()

    - #### getUserData

          public Object getUserData()

    - #### hasSID

          public boolean hasSID()

    - #### hasStateVariable

          public boolean hasStateVariable(String name)

    - #### isControlURL

          public boolean isControlURL(String url)

      Checks if the given URL matches this service's control URL.
      Parameters:
        `url` - the URL to check
      Returns:
        true if the URL matches the control URL, false otherwise

    - #### isEventSubURL

          public boolean isEventSubURL(String url)

      Checks if the given URL matches this service's event subscription URL.
      Parameters:
        `url` - the URL to check
      Returns:
        true if the URL matches the event subscription URL, false otherwise

    - #### isSCPDURL

          public boolean isSCPDURL(String url)

      Checks if the given URL matches this service's SCPD URL.
      Parameters:
        `url` - the URL to check
      Returns:
        true if the URL matches the SCPD URL, false otherwise

    - #### isService

          public boolean isService(String name)

    - #### isServiceNode

          public static boolean isServiceNode(Node node)

      Checks if the given XML node represents a service.
      Parameters:
        `node` - the XML node to check
      Returns:
        true if the node is a service node, false otherwise

    - #### isSubscribed

          public boolean isSubscribed()

    - #### loadSCPD

          public boolean loadSCPD(File file)
                           throws ParserException

      Loads service control point description (SCPD) from a file.
      Parameters:
        `file` - file containing SCPD XML
      Returns:
        true if SCPD was loaded successfully, false otherwise
      Throws:
        `ParserException` - if SCPD cannot be parsed

    - #### loadSCPD

          public boolean loadSCPD(InputStream input)
                           throws ParserException

      Loads service description (SCPD) from an input stream.
      Parameters:
        `input` - input stream containing SCPD XML
      Returns:
        true if SCPD was loaded successfully, false otherwise
      Throws:
        `ParserException` - if SCPD cannot be parsed

    - #### loadSCPD

          public boolean loadSCPD(String scpdStr)
                           throws InvalidDescriptionException

      Loads service control point description (SCPD) from a string.
      Parameters:
        `scpdStr` - the SCPD XML string to load
      Returns:
        true if SCPD was loaded successfully, false otherwise
      Throws:
        `InvalidDescriptionException` - if SCPD cannot be parsed

    - #### lock

          public void lock()

      Acquires exclusive lock on this service for thread-safe operations.

    - #### notify

          public void notify(StateVariable stateVar)

    - #### notifyAllStateVariables

          public void notifyAllStateVariables()

    - #### removeSubscriber

          public void removeSubscriber(Subscriber sub)

    - #### serviceSearchResponse

          public boolean serviceSearchResponse(SSDPPacket ssdpPacket)

    - #### setActionListener

          public void setActionListener(ActionListener listener)

    - #### setControlURL

          public void setControlURL(String value)

      Sets the control URL for this service.
      Parameters:
        `value` - the control URL to set

    - #### setDescriptionURL

          public void setDescriptionURL(String value)

      Sets the description URL for this service.
      Parameters:
        `value` - the description URL to set

    - #### setEventSubURL

          public void setEventSubURL(String value)

      Sets the event subscription URL for this service.
      Parameters:
        `value` - the event subscription URL to set

    - #### setQueryListener

          public void setQueryListener(QueryListener queryListener)

    - #### setSCPDURL

          public void setSCPDURL(String value)

      Sets the SCPD URL for this service.
      Parameters:
        `value` - the SCPD URL to set

    - #### setServiceID

          public void setServiceID(String value)

      Sets service ID of this service.
      Parameters:
        `value` - service ID string to set

    - #### setServiceType

          public void setServiceType(String value)

      Sets service type of this service.
      Parameters:
        `value` - service type string to set

    - #### setSID

          public void setSID(String id)

    - #### setTimeout

          public void setTimeout(long value)

    - #### setUserData

          public void setUserData(Object data)

    - #### unlock

          public void unlock()

      Releases exclusive lock on this service.

    - #### updateConfigId

          public void updateConfigId()

      Updates the configuration ID for this service based on its SCPD XML.