java.lang.Object
org.cybergarage.upnp.Service
public class Serviceextends Object
An UPnP service, described by an SCPD document and reached through its containing device.

  • Field Details

  • Constructor Details

    • 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 Details

    • getServiceNode

      public Node getServiceNode()
      Gets the XML node representing this service.
      Returns:
      the service XML node

    • lock

      public void lock()
      Acquires exclusive lock on this service for thread-safe operations.

    • unlock

      public void unlock()
      Releases exclusive lock on this service.

    • 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

    • getDeviceNode

      private Node getDeviceNode()
      Gets the device node containing this service.
      Returns:
      the device node, or null if not found

    • getRootNode

      private Node getRootNode()
      Gets the root node of the device description.
      Returns:
      the root node

    • getDevice

      public Device getDevice()
      Gets the device containing this service.
      Returns:
      the parent device

    • getRootDevice

      public Device getRootDevice()
      Gets the root device containing this service.
      Returns:
      the root device

    • setServiceType

      public void setServiceType(String value)
      Sets service type of this service.
      Parameters:
      value - service type string to set

    • getServiceType

      public String getServiceType()
      Gets the service type of this service.
      Returns:
      service type string, or empty string if not set

    • setServiceID

      public void setServiceID(String value)
      Sets service ID of this service.
      Parameters:
      value - service ID string to set

    • getServiceID

      public String getServiceID()
      Gets the service ID of this service.
      Returns:
      service ID string, or empty string if not set

    • updateConfigId

      public void updateConfigId()
      Updates the configuration ID for this service based on its SCPD XML.

    • getConfigId

      public int getConfigId()
      Gets the configuration ID for this service.
      Returns:
      the configuration ID, or 0 if not set

    • isURL

      private boolean isURL(String referenceUrl, String url)
      Checks if the given URL matches the reference URL, considering both absolute and relative URLs.
      Parameters:
      referenceUrl - the reference URL to compare against
      url - the URL to check
      Returns:
      true if the URLs match, false otherwise

    • setSCPDURL

      public void setSCPDURL(String value)
      Sets the SCPD URL for this service.
      Parameters:
      value - the SCPD URL to set

    • getSCPDURL

      public String getSCPDURL()
      Gets the SCPD URL for this service.
      Returns:
      the SCPD URL

    • 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

    • setControlURL

      public void setControlURL(String value)
      Sets the control URL for this service.
      Parameters:
      value - the control URL to set

    • getControlURL

      public String getControlURL()
      Gets the control URL for this service.
      Returns:
      the control URL

    • 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

    • setEventSubURL

      public void setEventSubURL(String value)
      Sets the event subscription URL for this service.
      Parameters:
      value - the event subscription URL to set

    • getEventSubURL

      public String getEventSubURL()
      Gets the event subscription URL for this service.
      Returns:
      the event subscription URL

    • 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

    • 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

    • 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

    • setDescriptionURL

      public void setDescriptionURL(String value)
      Sets the description URL for this service.
      Parameters:
      value - the description URL to set

    • getDescriptionURL

      public String getDescriptionURL()
      Gets the description URL for this service.
      Returns:
      the description URL

    • getSCPDNode

      private Node getSCPDNode(URL scpdUrl) throws ParserException
      Gets the SCPD node by parsing from a URL.
      Parameters:
      scpdUrl - the URL to parse SCPD from
      Returns:
      the parsed SCPD node
      Throws:
      ParserException - if parsing fails

    • getSCPDNode

      private Node getSCPDNode(File scpdFile) throws ParserException
      Gets the SCPD node by parsing from a file.
      Parameters:
      scpdFile - the file to parse SCPD from
      Returns:
      the parsed SCPD node
      Throws:
      ParserException - if parsing fails

    • getSCPDNode

      private Node getSCPDNode()
      Gets the SCPD node for this service, loading it if necessary.
      Returns:
      the SCPD node, or null if not available

    • 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

    • 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

    • 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

    • 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

    • getServiceStateTable

      public ServiceStateTable getServiceStateTable()
      Builds the state variable table for this service from its SCPD document.
      Returns:
      the state table, empty if the SCPD document declares none

    • getStateVariable

      public StateVariable getStateVariable(String name)
      Looks up a state variable in this service's state table.
      Parameters:
      name - the state variable name, matched exactly
      Returns:
      the state variable, or null if the service declares no such name

    • hasStateVariable

      public boolean hasStateVariable(String name)
      Test whether this service publishes the named state variable.
      Parameters:
      name - the state variable name to look for
      Returns:
      true if the service declares a state variable with that name

    • isService

      public boolean isService(String name)
      Test whether the given name identifies this service, either by its service type or by its service ID.
      Parameters:
      name - the service type or service ID to match; a null value returns false
      Returns:
      true if name ends with this service's type or its service ID

    • getServiceData

      private ServiceData getServiceData()
      Parses the service node.
      Returns:
      the parsed data of the service node

    • getNotifyServiceTypeNT

      private String getNotifyServiceTypeNT()
      Gives the service type as sent in notify messages.
      Returns:
      the service type as sent in notify messages

    • getNotifyServiceTypeUSN

      private String getNotifyServiceTypeUSN()
      Builds the search target string for notifications.
      Returns:
      the USN string

    • 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)
      Announces this service as gone to the network using SSDP.
      Parameters:
      bindAddr - bind address to send the announcement from

    • serviceSearchResponse

      public boolean serviceSearchResponse(SSDPPacket ssdpPacket)
      Answer an SSDP M-SEARCH that names this service.
      Parameters:
      ssdpPacket - the search request, whose ST header selects the target
      Returns:
      false if the request carries no ST header, true once any matching search response has been queued

    • setQueryListener

      public void setQueryListener(QueryListener queryListener)
      Register the listener invoked when any of this service's state variables is queried.
      Parameters:
      queryListener - the listener to attach to every state variable

    • getSubscriberList

      public SubscriberList getSubscriberList()
      Get the subscribers registered for this service.
      Returns:
      the service's subscriber list, empty if it has no subscribers

    • addSubscriber

      public void addSubscriber(Subscriber sub)
      Register a subscriber to receive event notifications for this service.
      Parameters:
      sub - the subscriber to add to the service's subscriber list

    • removeSubscriber

      public void removeSubscriber(Subscriber sub)
      Deregister a subscriber so it stops receiving event notifications.
      Parameters:
      sub - the subscriber to remove from the service's subscriber list

    • getSubscriber

      public Subscriber getSubscriber(String name)
      Look up a subscriber by its subscription ID.
      Parameters:
      name - the subscription ID to match
      Returns:
      the matching subscriber, or null if no subscriber carries that SID

    • notify

      private boolean notify(Subscriber sub, StateVariable stateVar)
      Sends a state variable's new value to one subscriber.
      Parameters:
      sub - the subscriber to notify
      stateVar - the variable whose value changed
      Returns:
      true if the notification was sent

    • notify

      public void notify(StateVariable stateVar)
      Send an event for one state variable to every current subscriber, dropping any that have expired first.
      Parameters:
      stateVar - the state variable whose name and value are announced

    • notifyAllStateVariables

      public void notifyAllStateVariables()
      Send an event for every state variable that is flagged to send events.

    • getSID

      public String getSID()
      Get this service's subscription ID.
      Returns:
      the subscription ID assigned to this service's subscriber

    • setSID

      public void setSID(String id)
      Set this service's subscription ID.
      Parameters:
      id - the subscription ID to record

    • clearSID

      public void clearSID()
      Discard the subscription ID and zero the timeout, marking the service as no longer subscribed.

    • hasSID

      public boolean hasSID()
      Test whether a subscription ID is currently recorded for this service.
      Returns:
      true if a non-empty subscription ID is set

    • isSubscribed

      public boolean isSubscribed()
      Test whether this service currently holds a subscription.
      Returns:
      true if a subscription ID is set

    • getTimeout

      public long getTimeout()
      Get the subscription timeout in seconds.
      Returns:
      the number of seconds this service's subscription remains valid

    • setTimeout

      public void setTimeout(long value)
      Set the subscription timeout.
      Parameters:
      value - the subscription lifetime in seconds; 0 expires it at once

    • setActionListener

      public void setActionListener(ActionListener listener)
      Register the listener invoked when one of this service's actions is invoked.
      Parameters:
      listener - the listener to attach to every action in the 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

    • setUserData

      public void setUserData(Object data)
      Attach an application object to this service, for retrieval by getUserData.
      Parameters:
      data - the object to record; may be null

    • getUserData

      public Object getUserData()
      Get the application object attached to this service.
      Returns:
      the object passed to setUserData, or null if none has been set