Module org.cybergarage.upnp
Package org.cybergarage.upnp

Class Action

java.lang.Object
org.cybergarage.upnp.Action
public class Action extends Object
Represents a UPnP action that can be invoked on a service.

Actions are methods exposed by UPnP services that can be called remotely by control points. Each action has a name, a list of input arguments, and a list of output arguments. Actions are defined in the service's SCPD (Service Control Protocol Definition) document.

This class provides methods to:

  • Set and retrieve action arguments
  • Invoke the action on a remote device via postControlAction()
  • Handle incoming action requests from control points via ActionListener
  • Access action execution status and response data

Thread-safety: This class uses internal synchronization via lock() and unlock() methods. Multiple threads can safely interact with the same action instance when using these synchronization methods.

Example usage for invoking an action on a device: 


 Service service = device.getService("urn:schemas-upnp-org:service:AVTransport:1");
 Action playAction = service.getAction("Play");
 playAction.setArgumentValue("InstanceID", "0");
 playAction.setArgumentValue("Speed", "1");
 boolean success = playAction.postControlAction();
 if (success) {
     System.out.println("Play action executed successfully");
 }
See Also:

  • Field Details

    • ELEM_NAME

      public static final String ELEM_NAME
      The XML element name for action nodes in SCPD documents.
      See Also:

  • Constructor Details

    • Action

      public Action(org.cybergarage.xml.Node serviceNode)
      Constructs a new action with the specified service node.

      Creates an empty action node that can be populated with action details.

      Parameters:
      serviceNode - the XML node representing the service that contains this action

    • Action

      public Action(org.cybergarage.xml.Node serviceNode, org.cybergarage.xml.Node actionNode)
      Constructs an action from existing service and action XML nodes.

      This constructor is typically used when parsing service descriptions to create action objects from the SCPD document.

      Parameters:
      serviceNode - the XML node representing the parent service
      actionNode - the XML node containing action definition and arguments

    • Action

      public Action(Action action)
      Creates a copy of an existing action.

      Note: This creates a shallow copy that references the same underlying XML nodes as the original action.

      Parameters:
      action - the action to copy

  • Method Details

    • getService

      public Service getService()
      Returns the service that contains this action.
      Returns:
      the parent service of this action

    • getActionNode

      public org.cybergarage.xml.Node getActionNode()
      Returns the underlying XML node representing this action.
      Returns:
      the action XML node

    • lock

      public void lock()
      Acquires the lock for this action.

      Use this method to synchronize access to the action from multiple threads. Always pair with unlock() to release the lock, preferably in a try-finally block.

      See Also:

    • unlock

      public void unlock()
      Releases the lock for this action.

      Should be called after lock() once the synchronized operation is complete.

      See Also:

    • isActionNode

      public static boolean isActionNode(org.cybergarage.xml.Node node)
      Checks if the given XML node represents an action element.
      Parameters:
      node - the XML node to check
      Returns:
      true if the node's name matches the action element name, false otherwise

    • setName

      public void setName(String value)
      Sets the name of this action.
      Parameters:
      value - the action name (e.g., "Play", "SetVolume")

    • getName

      public String getName()
      Returns the name of this action.
      Returns:
      the action name as defined in the SCPD document

    • getArgumentList

      public ArgumentList getArgumentList()
      Returns the complete list of arguments for this action.

      This includes both input and output arguments as defined in the service's SCPD document.

      Returns:
      the list of all arguments for this action
      See Also:

    • setArgumentList

      public void setArgumentList(ArgumentList al)
      Sets the argument list for this action.

      Replaces the existing argument list with the provided list. This method ensures that all arguments are properly associated with the action's service.

      Parameters:
      al - the argument list to set

    • getInputArgumentList

      public ArgumentList getInputArgumentList()
      Returns only the input arguments for this action.

      Input arguments are those with direction "in" and must be provided when invoking the action on a device.

      Returns:
      the list of input arguments
      See Also:

    • getOutputArgumentList

      public ArgumentList getOutputArgumentList()
      Returns only the output arguments for this action.

      Output arguments are those with direction "out" and are populated with values returned by the device after action execution.

      Returns:
      the list of output arguments
      See Also:

    • getArgument

      public Argument getArgument(String name)
      Returns the argument with the specified name.
      Parameters:
      name - the name of the argument to retrieve
      Returns:
      the argument with the specified name, or null if not found

    • setArgumentValues

      public void setArgumentValues(ArgumentList argList)
      Deprecated.
      You should use one of the following methods instead:
      - setInArgumentValues(ArgumentList)
      - setOutArgumentValues(ArgumentList)
      Sets argument values from the provided list.
      Parameters:
      argList - the argument list containing values to set

    • setInArgumentValues

      public void setInArgumentValues(ArgumentList argList)
      Sets the values of input arguments from the provided argument list.

      Only the values of arguments with direction "in" are updated.

      Parameters:
      argList - the argument list containing values to set
      Since:
      1.8.0

    • setOutArgumentValues

      public void setOutArgumentValues(ArgumentList argList)
      Sets the values of output arguments from the provided argument list.

      Only the values of arguments with direction "out" are updated.

      Parameters:
      argList - the argument list containing values to set
      Since:
      1.8.0

    • setArgumentValue

      public void setArgumentValue(String name, String value)
      Sets the value of a named argument.

      If the argument with the specified name does not exist, this method does nothing.

      Parameters:
      name - the name of the argument to set
      value - the string value to assign to the argument

    • setArgumentValue

      public void setArgumentValue(String name, int value)
      Sets the value of a named argument from an integer.

      The integer value is converted to a string before being assigned. If the argument with the specified name does not exist, this method does nothing.

      Parameters:
      name - the name of the argument to set
      value - the integer value to assign to the argument

    • getArgumentValue

      public String getArgumentValue(String name)
      Returns the string value of the specified argument.
      Parameters:
      name - the name of the argument
      Returns:
      the argument value as a string, or an empty string if the argument is not found

    • getArgumentIntegerValue

      public int getArgumentIntegerValue(String name)
      Returns the integer value of the specified argument.
      Parameters:
      name - the name of the argument
      Returns:
      the argument value as an integer, or 0 if the argument is not found

    • getActionListener

      public org.cybergarage.upnp.control.ActionListener getActionListener()
      Returns the action listener registered for this action.
      Returns:
      the action listener, or null if none is registered

    • setActionListener

      public void setActionListener(org.cybergarage.upnp.control.ActionListener listener)
      Sets the listener that will be notified when this action is invoked.

      The listener's ActionListener.actionControlReceived(Action) method will be called when a control point invokes this action.

      Parameters:
      listener - the action listener to set, or null to remove the listener
      See Also:
      • ActionListener

    • performActionListener

      public boolean performActionListener(org.cybergarage.upnp.control.ActionRequest actionReq)
      Executes the action listener for an incoming action request.

      This method is called by the UPnP device when a control point invokes this action. It calls the registered ActionListener, collects the response, and posts it back to the control point.

      Parameters:
      actionReq - the incoming action request from the control point
      Returns:
      true if a listener was registered and executed, false if no listener is available

    • getControlStatus

      public UPnPStatus getControlStatus()
      Returns the UPnP error status from the most recent control response.
      Returns:
      the UPnP status from the control response

    • postControlAction

      public boolean postControlAction()
      Posts this action to the device and waits for the response.

      This method sends a SOAP action request to the device's control URL with the currently set input argument values. It blocks until a response is received or a timeout occurs. Upon successful execution, the output argument values are updated with the response data.

      The execution status can be retrieved via getStatus() after this method returns.

      Returns:
      true if the action was executed successfully and the response was valid, false if an error occurred
      See Also:

    • print

      public void print()
      Prints action information to standard output for debugging.

      Outputs the action name and all argument details including direction, name, and current value.

    • setStatus

      public void setStatus(int code, String descr)
      Sets the execution status of this action with a specific error code and description.
      Parameters:
      code - the UPnP error code
      descr - the human-readable description of the error
      See Also:

    • setStatus

      public void setStatus(int code)
      Sets the execution status of this action with a specific error code.

      The description is automatically derived from the error code.

      Parameters:
      code - the UPnP error code
      See Also:

    • getStatus

      public UPnPStatus getStatus()
      Returns the current execution status of this action.

      The status includes error codes and descriptions from the most recent action execution.

      Returns:
      the UPnP status object containing execution results
      See Also:

    • setUserData

      public void setUserData(Object data)
      Sets custom user data associated with this action.

      This allows applications to attach arbitrary data to an action instance for application-specific purposes.

      Parameters:
      data - the user data object to associate with this action

    • getUserData

      public Object getUserData()
      Returns the custom user data associated with this action.
      Returns:
      the user data object, or null if none has been set