Perform an Action

After you create your AciService, the next thing you need to do to send an action to an ACI Server, is to produce a set of parameters. You can use any kind of Set implementation, and there is a helper class, ActionParameters, with various methods to make it easier to populate.

If you were sending a Query action to IDOL Server, you would create your ActionParameters like:

// Create the parameter set...
final ActionParameters parameters = new ActionParameters();
parameters.add(AciConstants.PARAM_ACTION, "Query");
parameters.add("Text", queryText);
parameters.add("combine", "simple");
parameters.add("maxResults", 10);
parameters.add("totalResults", true);
parameters.add("print", "none");
parameters.add("summary", "ParagraphConcept");
parameters.add("characters", 400);
parameters.add("anyLanguage", true);
parameters.add("outputEncoding", "utf8");

You can also specify parameters to the constructor, using varargs for example:

// Create the parameter set...
final ActionParameters parameters = new ActionParameters(
      new AciParameter(AciConstants.PARAM_ACTION, "Query"),
      new AciParameter("text", queryText),
      new AciParameter("combine", "simple"),
      new AciParameter("maxResults", 10),
      new AciParameter("totalResults", true),
      new AciParameter("print", "none"),
      new AciParameter("summary", "ParagraphConcept"),
      new AciParameter("characters", 400),
      new AciParameter("anyLanguage", true),
      new AciParameter("outputEncoding", "utf8")
);

The following example also shows a shorthand way to create your ActionParameters, where all you need is the action parameter:

final ActionParameters params = new ActionParameters("getstatus");

When you are passed a Set<ActionParameter>, you can easily convert this into an ActionParameters object by using the ActionParameters.convert(Set<? extends ActionParameter>) method. If the method is passed an ActionParameters object, it casts it back and returns it, without creating a new copy.

The default behavior of a Set is to not add something if it already exists in the set, so ActionParameters contains a series of put(AciParameter) methods, which remove the existing value and replace it with the one passed. This option ensures that certain parameters are set to required values, regardless of what has been passed. For example:

private void myMethod(final Set<ActionParameter<?>> parameterSet) {
    // Convert the set of parameters...
    final ActionParameters parameters = ActionParameters.convert(parameterSet);

    // Ensure that these parameters are set to the values that are required...
    parameters.put("combine", "simple");
    parameters.put("anyLanguage", true);
    parameters.put("outputEncoding", "utf8");

    ...
}

After you have your set of parameters, you can use the previously configured AciService to send them to your ACI Server. For example:

// Send the action and process the response into a DOM Document...
final Document response = aciService.executeAction(
      parameters, new DocumentProcessor());

As previously stated, you can also supply connection details at this point to override any already set on the default AciService implementation. For example:

// Send the action and process the response into a DOM Document...
final Document response = aciService.executeAction(
      new AciServerDetails(
            AciServerDetails.TransportProtocol.HTTPS, host, port),
      new ActionParameters("GetVersion"),
      new DocumentProcessor()
);