/*
 * $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 $
 *
 * Copyright (c) OSGi Alliance (2002, 2006). All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.osgi.service.upnp;

import java.util.Dictionary;

/**
 * A UPnP action.
 * 
 * Each UPnP service contains zero or more actions. Each action may have zero or
 * more UPnP state variables as arguments.
 *  
 */
public interface UPnPAction {
	/**
	 * Returns the action name.
	 * 
	 * The action name corresponds to the <code>name</code> field in the
	 * <code>actionList</code> of the service description.
	 * <ul>
	 * <li>For standard actions defined by a UPnP Forum working committee,
	 * action names must not begin with <code>X_ </code> nor <code> A_</code>.</li>
	 * <li>For non-standard actions specified by a UPnP vendor and added to a
	 * standard service, action names must begin with <code>X_</code>.</li>
	 * </ul>
	 * 
	 * @return Name of action, must not contain a hyphen character or a hash
	 *         character
	 */
	String getName();

	/**
	 * Returns the name of the designated return argument.
	 * <p>
	 * One of the output arguments can be flagged as a designated return
	 * argument.
	 * 
	 * @return The name of the designated return argument or <code>null</code> if
	 *         none is marked.
	 */
	String getReturnArgumentName();

	/**
	 * Lists all input arguments for this action.
	 * <p>
	 * Each action may have zero or more input arguments.
	 * 
	 * @return Array of input argument names or <code>null</code> if no input
	 *         arguments.
	 * 
	 * @see UPnPStateVariable
	 */
	String[] getInputArgumentNames();

	/**
	 * List all output arguments for this action.
	 * 
	 * @return Array of output argument names or <code>null</code> if there are no
	 *         output arguments.
	 * 
	 * @see UPnPStateVariable
	 */
	String[] getOutputArgumentNames();

	/**
	 * Finds the state variable associated with an argument name.
	 * 
	 * Helps to resolve the association of state variables with argument names
	 * in UPnP actions.
	 * 
	 * @param argumentName The name of the UPnP action argument.
	 * @return State variable associated with the named argument or
	 *         <code>null</code> if there is no such argument.
	 * 
	 * @see UPnPStateVariable
	 */
	UPnPStateVariable getStateVariable(String argumentName);

	/**
	 * Invokes the action.
	 * 
	 * The input and output arguments are both passed as <code>Dictionary</code>
	 * objects. Each entry in the <code>Dictionary</code> object has a
	 * <code>String</code> object as key representing the argument name and the
	 * value is the argument itself. The class of an argument value must be
	 * assignable from the class of the associated UPnP state variable.
	 * 
	 * The input argument <code>Dictionary</code> object must contain exactly
	 * those arguments listed by <code>getInputArguments</code> method. The output
	 * argument <code>Dictionary</code> object will contain exactly those
	 * arguments listed by <code>getOutputArguments</code> method.
	 *
	 * @param args A <code>Dictionary</code> of arguments. Must contain the correct set and
	 * type of arguments for this action. May be <code>null</code> if no
	 * input arguments exist.
	 *
	 * @return A <code>Dictionary</code> with the output arguments.
	 *         <code>null</code> if the action has no output arguments.
	 *
	 * @throws UPnPException  A UPnP error has occured.
	 * @throws Exception The execution fails for some reason.
	 *
	 * @see UPnPStateVariable
	 */
	Dictionary invoke(Dictionary args) throws Exception;
}