001 /*
002 * Copyright (c) OSGi Alliance (2002, 2008). All Rights Reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.osgi.service.upnp;
017
018 import java.util.Dictionary;
019
020 /**
021 * A UPnP action.
022 *
023 * Each UPnP service contains zero or more actions. Each action may have zero or
024 * more UPnP state variables as arguments.
025 *
026 * @version $Revision: 5673 $
027 */
028 public interface UPnPAction {
029 /**
030 * Returns the action name.
031 *
032 * The action name corresponds to the <code>name</code> field in the
033 * <code>actionList</code> of the service description.
034 * <ul>
035 * <li>For standard actions defined by a UPnP Forum working committee,
036 * action names must not begin with <code>X_ </code> nor <code> A_</code>.</li>
037 * <li>For non-standard actions specified by a UPnP vendor and added to a
038 * standard service, action names must begin with <code>X_</code>.</li>
039 * </ul>
040 *
041 * @return Name of action, must not contain a hyphen character or a hash
042 * character
043 */
044 String getName();
045
046 /**
047 * Returns the name of the designated return argument.
048 * <p>
049 * One of the output arguments can be flagged as a designated return
050 * argument.
051 *
052 * @return The name of the designated return argument or <code>null</code> if
053 * none is marked.
054 */
055 String getReturnArgumentName();
056
057 /**
058 * Lists all input arguments for this action.
059 * <p>
060 * Each action may have zero or more input arguments.
061 *
062 * @return Array of input argument names or <code>null</code> if no input
063 * arguments.
064 *
065 * @see UPnPStateVariable
066 */
067 String[] getInputArgumentNames();
068
069 /**
070 * List all output arguments for this action.
071 *
072 * @return Array of output argument names or <code>null</code> if there are no
073 * output arguments.
074 *
075 * @see UPnPStateVariable
076 */
077 String[] getOutputArgumentNames();
078
079 /**
080 * Finds the state variable associated with an argument name.
081 *
082 * Helps to resolve the association of state variables with argument names
083 * in UPnP actions.
084 *
085 * @param argumentName The name of the UPnP action argument.
086 * @return State variable associated with the named argument or
087 * <code>null</code> if there is no such argument.
088 *
089 * @see UPnPStateVariable
090 */
091 UPnPStateVariable getStateVariable(String argumentName);
092
093 /**
094 * Invokes the action.
095 *
096 * The input and output arguments are both passed as <code>Dictionary</code>
097 * objects. Each entry in the <code>Dictionary</code> object has a
098 * <code>String</code> object as key representing the argument name and the
099 * value is the argument itself. The class of an argument value must be
100 * assignable from the class of the associated UPnP state variable.
101 *
102 * The input argument <code>Dictionary</code> object must contain exactly
103 * those arguments listed by <code>getInputArguments</code> method. The output
104 * argument <code>Dictionary</code> object will contain exactly those
105 * arguments listed by <code>getOutputArguments</code> method.
106 *
107 * @param args A <code>Dictionary</code> of arguments. Must contain the correct set and
108 * type of arguments for this action. May be <code>null</code> if no
109 * input arguments exist.
110 *
111 * @return A <code>Dictionary</code> with the output arguments.
112 * <code>null</code> if the action has no output arguments.
113 *
114 * @throws UPnPException A UPnP error has occured.
115 * @throws Exception The execution fails for some reason.
116 *
117 * @see UPnPStateVariable
118 */
119 Dictionary invoke(Dictionary args) throws Exception;
120 }