org.fourthline.cling.model.meta.ActionArgument Java Examples

private ActionArgumentValue<RemoteService>[] getArguments(final Action<RemoteService> action) {
    @SuppressWarnings("unchecked")
    final ActionArgument<RemoteService>[] actionArguments = action.getArguments();
    final Map<String, Object> argumentValues = getArgumentValues();
    final List<ActionArgumentValue<RemoteService>> actionArgumentValues = new ArrayList<>(actionArguments.length);

    for (final ActionArgument<RemoteService> actionArgument : actionArguments) {
        if (actionArgument.getDirection() == Direction.IN) {
            final Object value = argumentValues.get(actionArgument.getName());
            logger.trace("Action {}: add arg value for {}: {} (expected datatype: {})", action.getName(),
                    actionArgument, value, actionArgument.getDatatype().getDisplayString());
            actionArgumentValues.add(new ActionArgumentValue<>(actionArgument, value));
        }
    }
    @SuppressWarnings("unchecked")
    final ActionArgumentValue<RemoteService>[] array = actionArgumentValues
            .toArray(new ActionArgumentValue[0]);
    return array;
}
 

/**
 * The UPnP spec says that action arguments must be in the order as declared
 * by the service. This method however is lenient, the action argument nodes
 * in the XML can be in any order, as long as they are all there everything
 * is OK.
 */
protected ActionArgumentValue[] readArgumentValues(NodeList nodeList, ActionArgument[] args)
        throws ActionException {

    List<Node> nodes = getMatchingNodes(nodeList, args);

    ActionArgumentValue[] values = new ActionArgumentValue[args.length];

    for (int i = 0; i < args.length; i++) {
    	
        ActionArgument arg = args[i];
        Node node = findActionArgumentNode(nodes, arg);
        if(node == null) {
            throw new ActionException(
                    ErrorCode.ARGUMENT_VALUE_INVALID,
                    "Could not find argument '" + arg.getName() + "' node");
        }
        log.fine("Reading action argument: " + arg.getName());
        String value = XMLUtil.getTextContent(node);
        values[i] = createValue(arg, value);
    }
    return values;
}
 

protected ActionArgumentValue[] readArgumentValues(XmlPullParser xpp, ActionArgument[] args) throws Exception {
    // We're in the <ActionName>Response tag
    Map<String, String> matches = getMatchingNodes(xpp, args);

    ActionArgumentValue[] values = new ActionArgumentValue[args.length];

    for (int i = 0; i < args.length; i++) {

        ActionArgument arg = args[i];
        String value = findActionArgumentValue(matches, arg);
        if (value == null) {
            throw new ActionException(
                ErrorCode.ARGUMENT_VALUE_INVALID,
                "Could not find argument '" + arg.getName() + "' node");
        }

        log.fine("Reading action argument: " + arg.getName());
        values[i] = createValue(arg, value);
    }
    return values;
}
 

@Override
public void endElement(ELEMENT element) throws SAXException {
    switch (element) {
        case name:
            getInstance().name = getCharacters();
            break;
        case direction:
            String directionString = getCharacters();
            try {
                getInstance().direction = ActionArgument.Direction.valueOf(directionString.toUpperCase(Locale.ENGLISH));
            } catch (IllegalArgumentException ex) {
                // TODO: UPNP VIOLATION: Pelco SpectraIV-IP uses illegal value INOUT
                log.warning("UPnP specification violation: Invalid action argument direction, assuming 'IN': " + directionString);
                getInstance().direction = ActionArgument.Direction.IN;
            }
            break;
        case relatedStateVariable:
            getInstance().relatedStateVariable = getCharacters();
            break;
        case retval:
            getInstance().retval = true;
            break;
    }
}
 

/**
 * Reads the output arguments after an action execution using accessors.
 *
 * @param action The action of which the output arguments are read.
 * @param instance The instance on which the accessors will be invoked.
 * @return <code>null</code> if the action has no output arguments, a single instance if it has one, an
 *         <code>Object[]</code> otherwise.
 * @throws Exception
 */
protected Object readOutputArgumentValues(Action<LocalService> action, Object instance) throws Exception {
    Object[] results = new Object[action.getOutputArguments().length];
    log.fine("Attempting to retrieve output argument values using accessor: " + results.length);

    int i = 0;
    for (ActionArgument outputArgument : action.getOutputArguments()) {
        log.finer("Calling acccessor method for: " + outputArgument);

        StateVariableAccessor accessor = getOutputArgumentAccessors().get(outputArgument);
        if (accessor != null) {
            log.fine("Calling accessor to read output argument value: " + accessor);
            results[i++] = accessor.read(instance);
        } else {
            throw new IllegalStateException("No accessor bound for: " + outputArgument);
        }
    }

    if (results.length == 1) {
        return results[0];
    }
    return results.length > 0 ? results : null;
}
 

public Action appendAction(Map<Action, ActionExecutor> actions) throws LocalServiceBindingException {

        String name;
        if (getAnnotation().name().length() != 0) {
            name = getAnnotation().name();
        } else {
            name = AnnotationLocalServiceBinder.toUpnpActionName(getMethod().getName());
        }

        log.fine("Creating action and executor: " + name);

        List<ActionArgument> inputArguments = createInputArguments();
        Map<ActionArgument<LocalService>, StateVariableAccessor> outputArguments = createOutputArguments();

        inputArguments.addAll(outputArguments.keySet());
        ActionArgument<LocalService>[] actionArguments =
                inputArguments.toArray(new ActionArgument[inputArguments.size()]);

        Action action = new Action(name, actionArguments);
        ActionExecutor executor = createExecutor(outputArguments);

        actions.put(action, executor);
        return action;
    }
 

/**
 * Reads the output arguments after an action execution using accessors.
 *
 * @param action The action of which the output arguments are read.
 * @param instance The instance on which the accessors will be invoked.
 * @return <code>null</code> if the action has no output arguments, a single instance if it has one, an
 *         <code>Object[]</code> otherwise.
 * @throws Exception
 */
protected Object readOutputArgumentValues(Action<LocalService> action, Object instance) throws Exception {
    Object[] results = new Object[action.getOutputArguments().length];
    log.fine("Attempting to retrieve output argument values using accessor: " + results.length);

    int i = 0;
    for (ActionArgument outputArgument : action.getOutputArguments()) {
        log.finer("Calling acccessor method for: " + outputArgument);

        StateVariableAccessor accessor = getOutputArgumentAccessors().get(outputArgument);
        if (accessor != null) {
            log.fine("Calling accessor to read output argument value: " + accessor);
            results[i++] = accessor.read(instance);
        } else {
            throw new IllegalStateException("No accessor bound for: " + outputArgument);
        }
    }

    if (results.length == 1) {
        return results[0];
    }
    return results.length > 0 ? results : null;
}
 

protected ActionArgumentValue[] readArgumentValues(XmlPullParser xpp, ActionArgument[] args) throws Exception {
    // We're in the <ActionName>Response tag
    Map<String, String> matches = getMatchingNodes(xpp, args);

    ActionArgumentValue[] values = new ActionArgumentValue[args.length];

    for (int i = 0; i < args.length; i++) {

        ActionArgument arg = args[i];
        String value = findActionArgumentValue(matches, arg);
        if (value == null) {
            throw new ActionException(
                ErrorCode.ARGUMENT_VALUE_INVALID,
                "Could not find argument '" + arg.getName() + "' node");
        }

        log.fine("Reading action argument: " + arg.getName());
        values[i] = createValue(arg, value);
    }
    return values;
}
 

/**
 * The UPnP spec says that action arguments must be in the order as declared
 * by the service. This method however is lenient, the action argument nodes
 * in the XML can be in any order, as long as they are all there everything
 * is OK.
 */
protected ActionArgumentValue[] readArgumentValues(NodeList nodeList, ActionArgument[] args)
        throws ActionException {

    List<Node> nodes = getMatchingNodes(nodeList, args);

    ActionArgumentValue[] values = new ActionArgumentValue[args.length];

    for (int i = 0; i < args.length; i++) {
    	
        ActionArgument arg = args[i];
        Node node = findActionArgumentNode(nodes, arg);
        if(node == null) {
            throw new ActionException(
                    ErrorCode.ARGUMENT_VALUE_INVALID,
                    "Could not find argument '" + arg.getName() + "' node");
        }
        log.fine("Reading action argument: " + arg.getName());
        String value = XMLUtil.getTextContent(node);
        values[i] = createValue(arg, value);
    }
    return values;
}
 

public Action appendAction(Map<Action, ActionExecutor> actions) throws LocalServiceBindingException {

        String name;
        if (getAnnotation().name().length() != 0) {
            name = getAnnotation().name();
        } else {
            name = AnnotationLocalServiceBinder.toUpnpActionName(getMethod().getName());
        }

        log.fine("Creating action and executor: " + name);

        List<ActionArgument> inputArguments = createInputArguments();
        Map<ActionArgument<LocalService>, StateVariableAccessor> outputArguments = createOutputArguments();

        inputArguments.addAll(outputArguments.keySet());
        ActionArgument<LocalService>[] actionArguments =
                inputArguments.toArray(new ActionArgument[inputArguments.size()]);

        Action action = new Action(name, actionArguments);
        ActionExecutor executor = createExecutor(outputArguments);

        actions.put(action, executor);
        return action;
    }
 

@Override
public void endElement(ELEMENT element) throws SAXException {
    switch (element) {
        case name:
            getInstance().name = getCharacters();
            break;
        case direction:
            String directionString = getCharacters();
            try {
                getInstance().direction = ActionArgument.Direction.valueOf(directionString.toUpperCase(Locale.ENGLISH));
            } catch (IllegalArgumentException ex) {
                // TODO: UPNP VIOLATION: Pelco SpectraIV-IP uses illegal value INOUT
                log.warning("UPnP specification violation: Invalid action argument direction, assuming 'IN': " + directionString);
                getInstance().direction = ActionArgument.Direction.IN;
            }
            break;
        case relatedStateVariable:
            getInstance().relatedStateVariable = getCharacters();
            break;
        case retval:
            getInstance().retval = true;
            break;
    }
}
 

public void hydrateActionArgument(MutableActionArgument actionArgument, Node actionArgumentNode) {

        NodeList argumentNodeChildren = actionArgumentNode.getChildNodes();
        for (int i = 0; i < argumentNodeChildren.getLength(); i++) {
            Node argumentNodeChild = argumentNodeChildren.item(i);

            if (argumentNodeChild.getNodeType() != Node.ELEMENT_NODE)
                continue;

            if (ELEMENT.name.equals(argumentNodeChild)) {
                actionArgument.name = XMLUtil.getTextContent(argumentNodeChild);
            } else if (ELEMENT.direction.equals(argumentNodeChild)) {
                String directionString = XMLUtil.getTextContent(argumentNodeChild);
                try {
                    actionArgument.direction = ActionArgument.Direction.valueOf(directionString.toUpperCase(Locale.ENGLISH));
                } catch (IllegalArgumentException ex) {
                    // TODO: UPNP VIOLATION: Pelco SpectraIV-IP uses illegal value INOUT
                    log.warning("UPnP specification violation: Invalid action argument direction, assuming 'IN': " + directionString);
                    actionArgument.direction = ActionArgument.Direction.IN;
                }
            } else if (ELEMENT.relatedStateVariable.equals(argumentNodeChild)) {
                actionArgument.relatedStateVariable = XMLUtil.getTextContent(argumentNodeChild);
            } else if (ELEMENT.retval.equals(argumentNodeChild)) {
                actionArgument.retval = true;
            }
        }
    }
 

private void generateActionArgument(ActionArgument actionArgument, Document descriptor, Element actionElement) {

        Element actionArgumentElement = appendNewElement(descriptor, actionElement, ELEMENT.argument);

        appendNewElementIfNotNull(descriptor, actionArgumentElement, ELEMENT.name, actionArgument.getName());
        appendNewElementIfNotNull(descriptor, actionArgumentElement, ELEMENT.direction, actionArgument.getDirection().toString().toLowerCase(Locale.ENGLISH));
        if (actionArgument.isReturnValue()) {
            // TODO: UPNP VIOLATION: WMP12 will discard RenderingControl service if it contains <retval> tags
            log.warning("UPnP specification violation: Not producing <retval> element to be compatible with WMP12: " + actionArgument);
            // appendNewElement(descriptor, actionArgumentElement, ELEMENT.retval);
        }
        appendNewElementIfNotNull(descriptor, actionArgumentElement, ELEMENT.relatedStateVariable, actionArgument.getRelatedStateVariableName());
    }
 

protected boolean isUseOutputArgumentAccessors(ActionInvocation<LocalService> actionInvocation) {
    for (ActionArgument argument : actionInvocation.getAction().getOutputArguments()) {
        // If there is one output argument for which we have an accessor, all arguments need accessors
        if (getOutputArgumentAccessors().get(argument) != null) {
            return true;
        }
    }
    return false;
}
 

protected void writeActionOutputArguments(Document d,
                                          Element actionResponseElement,
                                          ActionInvocation actionInvocation) {

    for (ActionArgument argument : actionInvocation.getAction().getOutputArguments()) {
        log.fine("Writing action output argument: " + argument.getName());
        String value = actionInvocation.getOutput(argument) != null ? actionInvocation.getOutput(argument).toString() : "";
        XMLUtil.appendNewElement(d, actionResponseElement, argument.getName(), value);
    }
}
 

public ActionArgument[] createActionArgumennts() {
    ActionArgument[] array = new ActionArgument[arguments.size()];
    int i = 0;
    for (MutableActionArgument argument : arguments) {
        array[i++] = argument.build();
    }
    return array;
}
 

/**
 * Finds all element nodes in the list that match any argument name or argument
 * alias, throws {@link ActionException} if not all arguments were found.
 */
protected List<Node> getMatchingNodes(NodeList nodeList, ActionArgument[] args) throws ActionException {

    List<String> names = new ArrayList();
    for (ActionArgument argument : args) {
        names.add(argument.getName());
        names.addAll(Arrays.asList(argument.getAliases()));
    }

    List<Node> matches = new ArrayList();
    for (int i = 0; i < nodeList.getLength(); i++) {
        Node child = nodeList.item(i);

        if (child.getNodeType() != Node.ELEMENT_NODE)
            continue;

        if (names.contains(getUnprefixedNodeName(child)))
            matches.add(child);
    }

    if (matches.size() < args.length) {
        throw new ActionException(
                ErrorCode.ARGUMENT_VALUE_INVALID,
                "Invalid number of input or output arguments in XML message, expected " + args.length + " but found " + matches.size()
        );
    }
    return matches;
}
 

/**
 * Creates an instance of {@link ActionArgumentValue} and wraps an
 * {@link InvalidValueException} as an {@link ActionException} with the
 * appropriate {@link ErrorCode}.
 */
protected ActionArgumentValue createValue(ActionArgument arg, String value) throws ActionException {
    try {
        return new ActionArgumentValue(arg, value);
    } catch (InvalidValueException ex) {
        throw new ActionException(
                ErrorCode.ARGUMENT_VALUE_INVALID,
                "Wrong type or invalid value for '" + arg.getName() + "': " + ex.getMessage(),
                ex
        );
    }
}
 

/**
 * Returns the node with the same unprefixed name as the action argument
 * name/alias or <code>null</code>.
 */
protected Node findActionArgumentNode(List<Node> nodes, ActionArgument arg) {
	for(Node node : nodes) {
		if(arg.isNameOrAlias(getUnprefixedNodeName(node))) return node;
	}
	return null;
}
 

public ActionArgument[] createActionArgumennts() {
    ActionArgument[] array = new ActionArgument[arguments.size()];
    int i = 0;
    for (MutableActionArgument argument : arguments) {
        array[i++] = argument.build();
    }
    return array;
}
 

/**
 * Returns the node with the same unprefixed name as the action argument
 * name/alias or <code>null</code>.
 */
protected Node findActionArgumentNode(List<Node> nodes, ActionArgument arg) {
	for(Node node : nodes) {
		if(arg.isNameOrAlias(getUnprefixedNodeName(node))) return node;
	}
	return null;
}
 

protected void writeActionOutputArguments(Document d,
                                          Element actionResponseElement,
                                          ActionInvocation actionInvocation) {

    for (ActionArgument argument : actionInvocation.getAction().getOutputArguments()) {
        log.fine("Writing action output argument: " + argument.getName());
        String value = actionInvocation.getOutput(argument) != null ? actionInvocation.getOutput(argument).toString() : "";
        XMLUtil.appendNewElement(d, actionResponseElement, argument.getName(), value);
    }
}
 

/**
 * Creates an instance of {@link ActionArgumentValue} and wraps an
 * {@link InvalidValueException} as an {@link ActionException} with the
 * appropriate {@link ErrorCode}.
 */
protected ActionArgumentValue createValue(ActionArgument arg, String value) throws ActionException {
    try {
        return new ActionArgumentValue(arg, value);
    } catch (InvalidValueException ex) {
        throw new ActionException(
                ErrorCode.ARGUMENT_VALUE_INVALID,
                "Wrong type or invalid value for '" + arg.getName() + "': " + ex.getMessage(),
                ex
        );
    }
}
 

private void generateAction(Action action, Document descriptor, Element actionListElement) {

        Element actionElement = appendNewElement(descriptor, actionListElement, ELEMENT.action);

        appendNewElementIfNotNull(descriptor, actionElement, ELEMENT.name, action.getName());

        if (action.hasArguments()) {
            Element argumentListElement = appendNewElement(descriptor, actionElement, ELEMENT.argumentList);
            for (ActionArgument actionArgument : action.getArguments()) {
                generateActionArgument(actionArgument, descriptor, argumentListElement);
            }
        }
    }
 

private void generateActionArgument(ActionArgument actionArgument, Document descriptor, Element actionElement) {

        Element actionArgumentElement = appendNewElement(descriptor, actionElement, ELEMENT.argument);

        appendNewElementIfNotNull(descriptor, actionArgumentElement, ELEMENT.name, actionArgument.getName());
        appendNewElementIfNotNull(descriptor, actionArgumentElement, ELEMENT.direction, actionArgument.getDirection().toString().toLowerCase(Locale.ENGLISH));
        if (actionArgument.isReturnValue()) {
            // TODO: UPNP VIOLATION: WMP12 will discard RenderingControl service if it contains <retval> tags
            log.warning("UPnP specification violation: Not producing <retval> element to be compatible with WMP12: " + actionArgument);
            // appendNewElement(descriptor, actionArgumentElement, ELEMENT.retval);
        }
        appendNewElementIfNotNull(descriptor, actionArgumentElement, ELEMENT.relatedStateVariable, actionArgument.getRelatedStateVariableName());
    }
 

/**
 * Finds all element nodes in the list that match any argument name or argument
 * alias, throws {@link ActionException} if not all arguments were found.
 */
protected List<Node> getMatchingNodes(NodeList nodeList, ActionArgument[] args) throws ActionException {

    List<String> names = new ArrayList();
    for (ActionArgument argument : args) {
        names.add(argument.getName());
        names.addAll(Arrays.asList(argument.getAliases()));
    }

    List<Node> matches = new ArrayList();
    for (int i = 0; i < nodeList.getLength(); i++) {
        Node child = nodeList.item(i);

        if (child.getNodeType() != Node.ELEMENT_NODE)
            continue;

        if (names.contains(getUnprefixedNodeName(child)))
            matches.add(child);
    }

    if (matches.size() < args.length) {
        throw new ActionException(
                ErrorCode.ARGUMENT_VALUE_INVALID,
                "Invalid number of input or output arguments in XML message, expected " + args.length + " but found " + matches.size()
        );
    }
    return matches;
}
 

protected boolean isUseOutputArgumentAccessors(ActionInvocation<LocalService> actionInvocation) {
    for (ActionArgument argument : actionInvocation.getAction().getOutputArguments()) {
        // If there is one output argument for which we have an accessor, all arguments need accessors
        if (getOutputArgumentAccessors().get(argument) != null) {
            return true;
        }
    }
    return false;
}
 

/**
 * Sets the output argument value on the {@link org.fourthline.cling.model.action.ActionInvocation}, considers string conversion.
 */
protected void setOutputArgumentValue(ActionInvocation<LocalService> actionInvocation, ActionArgument<LocalService> argument, Object result)
        throws ActionException {

    LocalService service = actionInvocation.getAction().getService();

    if (result != null) {
        try {
            if (service.isStringConvertibleType(result)) {
                log.fine("Result of invocation matches convertible type, setting toString() single output argument value");
                actionInvocation.setOutput(new ActionArgumentValue(argument, result.toString()));
            } else {
                log.fine("Result of invocation is Object, setting single output argument value");
                actionInvocation.setOutput(new ActionArgumentValue(argument, result));
            }
        } catch (InvalidValueException ex) {
            throw new ActionException(
                    ErrorCode.ARGUMENT_VALUE_INVALID,
                    "Wrong type or invalid value for '" + argument.getName() + "': " + ex.getMessage(),
                    ex
            );
        }
    } else {

        log.fine("Result of invocation is null, not setting any output argument value(s)");
    }

}
 

protected Map<String, String> getMatchingNodes(XmlPullParser xpp, ActionArgument[] args) throws Exception {

        // This is a case-insensitive search!
        List<String> names = new ArrayList<String>();
        for (ActionArgument argument : args) {
            names.add(argument.getName().toUpperCase());
            for (String alias : Arrays.asList(argument.getAliases())) {
                names.add(alias.toUpperCase());
            }
        }

        Map<String, String> matches = new HashMap<String, String>();

        String enclosingTag = xpp.getName();

        int event;
        do {
            event = xpp.next();
            if(event == XmlPullParser.START_TAG && names.contains(xpp.getName().toUpperCase())) {
                matches.put(xpp.getName(), xpp.nextText());
            }

        }
        while (event != XmlPullParser.END_DOCUMENT && (event != XmlPullParser.END_TAG || !xpp.getName().equals(enclosingTag)));

        if (matches.size() < args.length) {
            throw new ActionException(
                ErrorCode.ARGUMENT_VALUE_INVALID,
                "Invalid number of input or output arguments in XML message, expected "
                    + args.length + " but found " + matches.size()
            );
        }
        return matches;
    }
 

protected void writeActionInputArguments(Document d,
                                         Element actionRequestElement,
                                         ActionInvocation actionInvocation) {

    for (ActionArgument argument : actionInvocation.getAction().getInputArguments()) {
        log.fine("Writing action input argument: " + argument.getName());
        String value = actionInvocation.getInput(argument) != null ? actionInvocation.getInput(argument).toString() : "";
        XMLUtil.appendNewElement(d, actionRequestElement, argument.getName(), value);
    }
}