KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > osgi > service > upnp > 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 JavaDoc;
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 JavaDoc 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 JavaDoc 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 JavaDoc[] 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 JavaDoc[] 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 JavaDoc 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 JavaDoc invoke(Dictionary JavaDoc args) throws Exception JavaDoc;
121 }
122
Popular Tags