UPnPAction


1   /*
2    * $Header: /cvshome/build/org.osgi.service.upnp/src/org/osgi/service/upnp/UPnPAction.java,v 1.10 2006/06/16 16:31:46 hargrave Exp $
3    *
4    * Copyright (c) OSGi Alliance (2002, 2006). All Rights Reserved.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *      http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  package org.osgi.service.upnp;
19  
20  import java.util.Dictionary  ;
21  
22  /**
23   * A UPnP action.
24   * 
25   * Each UPnP service contains zero or more actions. Each action may have zero or
26   * more UPnP state variables as arguments.
27   *  
28   */
29  public interface UPnPAction {
30      /**
31       * Returns the action name.
32       * 
33       * The action name corresponds to the <code>name</code> field in the
34       * <code>actionList</code> of the service description.
35       * <ul>
36       * <li>For standard actions defined by a UPnP Forum working committee,
37       * action names must not begin with <code>X_ </code> nor <code> A_</code>.</li>
38       * <li>For non-standard actions specified by a UPnP vendor and added to a
39       * standard service, action names must begin with <code>X_</code>.</li>
40       * </ul>
41       * 
42       * @return Name of action, must not contain a hyphen character or a hash
43       *         character
44       */
45      String   getName();
46  
47      /**
48       * Returns the name of the designated return argument.
49       * <p>
50       * One of the output arguments can be flagged as a designated return
51       * argument.
52       * 
53       * @return The name of the designated return argument or <code>null</code> if
54       *         none is marked.
55       */
56      String   getReturnArgumentName();
57  
58      /**
59       * Lists all input arguments for this action.
60       * <p>
61       * Each action may have zero or more input arguments.
62       * 
63       * @return Array of input argument names or <code>null</code> if no input
64       *         arguments.
65       * 
66       * @see UPnPStateVariable
67       */
68      String  [] getInputArgumentNames();
69  
70      /**
71       * List all output arguments for this action.
72       * 
73       * @return Array of output argument names or <code>null</code> if there are no
74       *         output arguments.
75       * 
76       * @see UPnPStateVariable
77       */
78      String  [] getOutputArgumentNames();
79  
80      /**
81       * Finds the state variable associated with an argument name.
82       * 
83       * Helps to resolve the association of state variables with argument names
84       * in UPnP actions.
85       * 
86       * @param argumentName The name of the UPnP action argument.
87       * @return State variable associated with the named argument or
88       *         <code>null</code> if there is no such argument.
89       * 
90       * @see UPnPStateVariable
91       */
92      UPnPStateVariable getStateVariable(String   argumentName);
93  
94      /**
95       * Invokes the action.
96       * 
97       * The input and output arguments are both passed as <code>Dictionary</code>
98       * objects. Each entry in the <code>Dictionary</code> object has a
99       * <code>String</code> object as key representing the argument name and the
100      * value is the argument itself. The class of an argument value must be
101      * assignable from the class of the associated UPnP state variable.
102      * 
103      * The input argument <code>Dictionary</code> object must contain exactly
104      * those arguments listed by <code>getInputArguments</code> method. The output
105      * argument <code>Dictionary</code> object will contain exactly those
106      * arguments listed by <code>getOutputArguments</code> method.
107      *
108      * @param args A <code>Dictionary</code> of arguments. Must contain the correct set and
109      * type of arguments for this action. May be <code>null</code> if no
110      * input arguments exist.
111      *
112      * @return A <code>Dictionary</code> with the output arguments.
113      *         <code>null</code> if the action has no output arguments.
114      *
115      * @throws UPnPException  A UPnP error has occured.
116      * @throws Exception The execution fails for some reason.
117      *
118      * @see UPnPStateVariable
119      */
120     Dictionary   invoke(Dictionary   args) throws Exception  ;
121 }
122
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags