Navigation Plan for Web Services User Guide

(1)

Navigation Plan for Web Services

User Guide

(February 4th, 2008)

Mauricio Chui Rodrigues

(2)

1. Compatibility with NPWS

There are two NPWS versions: one based on JAX-RPC (Java API for XML-Based RPC) and one based on JAX-WS (Java API for XML-Based Web Services). Both can only be called with messages in XML (Extended Markup Language), so an application can contact NPWS only if its programming language supports this kind of communication.

XML facilitates communication between different systems and it’s so popular that most programming languages support XML messages exchange. Just check if this is your case and get ready to use NPWS.

1.1. JAX-WS x JAX-RPC

JAX-WS is a more recent technology than JAX-RPC for developing Web services in Java. More precisely, it’s an evolved JAX-RPC with a new name. JAX-WS has many advantages over JAX-RPC, but old application servers may not contain it.

During the tests with NPWS, initially done with Java clients, JBoss AS 4.0.5 (JBoss Application Server 4.0.5) and JAX-RPC, I found a bug when trying to convert string arrays in XML to Java. Despite the efforts, I couldn’t find a solution and so decided to change NPWS functions in order to return long strings. These strings should be parsed by clients and then transformed into arrays.

When JBoss AS 4.2.X series became stable, JAX-WS gained support and I tried once again. As the string arrays were correctly mapped, I decided to develop a new NPWS version which returned string arrays to clients. Therefore there’s one version for each technology, but the JAX-WS one is much more recommended.

The server’s administrator is responsible for telling the users what NPWS version is deployed on server. If you’re curious and want to know how to configure a server, just read the tutorial on http://www.ime.usp.br/~chui/npws/doc/tutorials/eng/tutorial_server.pdf.

2. Ways of Executing Steps

When NavigationPlanTool informs that a step X is available for execution, the client should know how to execute X. The execution can occur in many ways: by calling a function, creating a thread, asking the user to do something (e.g., to put a book on a book shelf), etc.

With NPWS, steps (actions, rules or functions) can be exposed as Web services.

Therefore there are two ways of executing steps: one for steps that are exposed and other for the non-exposed ones. Some NPWS clients may not need exposed steps, that’s the case of any client which only performs local execution, using its own code.

(4)

The exposition as a Web service allows a step to be represented by any application on a network. In this case, NPWS asks the service to start execution, which is finished only when the service calls NPWS back and returns the results (if existent). Details about how to expose steps can be found on Section 3.

When a step isn’t exposed as a Web service, the client is responsible for all the execution. After it’s been started and finished, the client must contact NPWS and notify a service about the execution. If the step was a rule or a function, the client must also send results.

2.1. Differences between Execution Calls

A step exposed as a Web service must have the preffix "WS::" in its execution call.

When this preffix is found, a service of NPWS validates the execution call and then tries to call the service. If the preffix isn’t found, the execution call won’t be verified and it can be anything.

An user who defines a step as a Web service must format its execution call as following:

WS::WSDL_FILE_URL!SERVICE_NAMESPACE_URL!SERVICE_NAME

WSDL (Web Services Description Language) is an XML-based language for describing Web services. The first URL points to a file which has information about the service and its functions, while the second URL and the service’s name are important for the service to be found. All this stuff should be known by the step’s creator but, if the service is on JBoss AS, data can be gathered on http://HOST:DOOR/jbossws/services.

2.2. Functions for Execution

Each kind of step (action, rule or function) has two ways of being executed, according to its exposition as a Web service. The functions are listed below, but their details are on Section 5.4.2.

These functions try to start the execution of an exposed step. The Web services are responsible for finishing the execution and returning results (if existent):

long startActionWS(long actionId, long instanceId) long startRuleWS(long ruleId, long instanceId)

long startFunctionWS(long functionId, long instanceId)

(5)

Non-exposed steps must have their execution started and finished by the client. The following functions are called to notify NPWS that execution’s been performed. If the step is a rule, the client must inform if the result was true (1) or false (0). If the step is a function, the client must inform the resulting integer value.

long executeAction(long actionId, long instanceId)

long executeRule(long ruleId, long instanceId, int bool)

long executeFunction(long functionId, long instanceId, int value)

3. How to Expose Steps

Every exposed step has a Web interface which receives XML messages, therefore the step can be implemented in any programming language as long as it supports this kind of communication. However, there are two important restrictions:

1-) The service’s interface must expose the function execute, which doesn’t need parameters and is responsible for starting the step’s execution (e.g., creating a thread). This function must return 0 to inform that execution’s been successfully started. Then NPWS will contact NavigationPlanTool to update the step’s status.

2-) When execution’s been finished, the service must contact NPWS by calling the service Ending. This part of NPWS was prepared to deal with calls from other Web services.

3.1. The Service Ending

3.1.1. Information

Name Ending

Allows To register that the execution of exposed steps has been finished.

WSDL File http://HOST:DOOR/NPWS/EndingBean?wsdl

3.1.2. Functions

void endAction(long actionLogId, long instanceId)

> Utility

Finishes an action of a process' instance.

> Parameters

(6)

- instanceId: ID of the related instance.

void endRule(long ruleLogId, long instanceId, int bool)

> Utility

Finishes a rule of a process' instance.

> Parameters

- ruleLogId: log ID of the rule to be finished;

- instanceId: ID of the related instance;

- bool: result obtained when the rule was executed and that may be 1 (true) or 0 (false).

void endFunction(long functionLogId, long instanceId, int value)

> Utility

Finishes a function of a process' instance.

> Parameters

- functionLogId: log ID of the function to be finished;

- value: result obtained when the function was executed.

3.2. Sample Web Services

There are four optional sample Web services for testing NPWS with exposed steps:

SampleAction, SampleTrueRule, SampleFalseRule and SampleFunction. If these services are available on a server, they can be used by users who are interested in performing this kind of execution.

Each sample step exposes the function execute in its interface. This function creates a detached thread and returns the value 0 for the step to be setted as started. The new thread waits five seconds and then notifies NPWS that execution’s been finished. SampleTrueRule and SampleFalseRule return, respectively, 1 (true) and 0 (false). SampleFunction returns the value 3 and SampleAction doesn’t return anything.

These Web services are very simple to use, just get the following information and define a step with an execution call as described on Section 2.1. The four Web services have the namespace http://samples/jaws (JAX-RPC) or http://endpoints.samplews.ime.usp.br/

(JAX-WS).

- Service’s name: SampleAction

(7)

- WSDL file: http://HOST:DOOR/Samples/SampleActionBean?wsdl

- Service’s name: SampleTrueRule

- WSDL file: http://HOST:DOOR/Samples/SampleTrueRuleBean?wsdl

- Service’s name: SampleFalseRule

- WSDL file: http://HOST:DOOR/Samples/SampleFalseRuleBean?wsdl

- Service’s name: SampleFunction

- WSDL file: http://HOST:DOOR/Samples/SampleFunctionBean?wsdl

4. How to Use NPWS

Although NavigationPlanTool offers many functions for dealing with processes, processes’ instances and steps, users are usually more interested in how to execute the instances. However, before doing that, a process has to be created, defined and instantiated.

On this section you’ll find a guide for executing instances with NPWS. There’s also a simple example which allows you to perform each step using the sample client. As long as the client is available on a server, it can be accessed on http://HOST:DOOR/npws_demo/. If you want to learn how to implement a client, see the Appendix.

4.1. Creating the Steps and the Process

The creation is done by sending NPDL commands to NPWS and consists in calling the function execute on service Commands. This function receives a string with one or more commands and pass it to NavigationPlanTool. Then the commands are analyzed and, if the tool doesn’t find errors, they’re executed.

Example:

You’ll need a process, an action, a rule and a function. The three steps won’t be exposed as Web services, so any execution call would be valid. The process could also have anything as description. However, everything will be defined to indicate tests. Open the application for NPDL commands and type the following lines (you can also send each command as a new string):

CREATE ACTION A1 'Action for tests';

CREATE RULE R1 'Rule for tests';

CREATE FUNCTION F1 'Function for tests';

CREATE PROCESS P1 'Process for tests';

(8)

If one of the names already exists, you’ll have to replace it with a new name. You can see the names in use by sending one of these commands:

SELECT ACTIONS;

SELECT RULES;

SELECT FUNCTIONS;

SELECT PROCESSES;

When you use the application for NPDL commands, you’re actually invoking the function execute (e.g., execute("CREATE ACTION...")).

4.2. Defining the Process

Processes’ definitions are also done with NPDL commands, so the function execute on service Commands is called again. A process can only be defined if the involved steps exist: the commands for creation must have been sent in a previous string.

Example:

Use the same application as before and send the following string, which defines the process P1:

SET P1 = %R1 (A1 ?F1) + %!R1 A1;

The above definition corresponds to this logic: if rule R1 is executed and it returns true, action A1 will be executed N times, where N is an integer value returned by the function F1; if R1 returns false, A1 will be executed once.

4.3. Instantiating the Process

The function for instantiating the process is createProcessInstance on service Processes. Its parameters are the process’ name and a name which identifies the instance’s creator. The returned value is the instance’s identifier that can be used to start execution.

Example:

Open the control application and find P1 on the list of processes. Click the link and you’ll see information about P1 next to the list. Now choose “Create instance” for P1 to be instantiated with the call createProcessInstance(“P1”, “WebClient”).

(9)

(10)

4.4. Executing the Instance

Once you’ve created an instance, you can execute it. This involves identifying what steps are available at the moment and choosing one for execution. This process is repeated until execution ends.

The essential functions belong to service Instances and receive the instance’s identifier: isExecutionFinished verifies the condition; listProcessInstanceCurrentActions, listProcessInstanceCurrentRules and listProcessInstanceCurrentFunctions ask for available steps. The functions for execution are found on Section 2.2.

If you want to implement the execution cycle, read the functions’ descriptions and their return values on Section 5.3.2. Once the cycle’s been started, you can continue it at any moment, since the changes are stored in a database. Here is the logic you should implement:

while (isExecutionFinished() != 1) {

info1 = listProcessInstanceCurrentActions();

info2 = listProcessInstanceCurrentRules();

info3 = listProcessInstanceCurrentFunctions();

if (nothing new in info1, info2 and info3) wait();

else

executeSomething();

}

Example:

Still using the control application, choose an instance on the list of instances. Its information includes the option for execution: click it to open a new window. While execution isn’t finished, the application shows an waiting message and keeps verifying if there’s an available action, rule or function. When this happens, the steps’ data (including their identifiers) are received.

As the steps aren’t exposed as Web services, the application’s going to ask you the

“returned” values for R1 and F1. If you define that R1 has returned true, the application will send the value 1 as the third parameter of executeRule; else it will send 0. The value chosen for F1 will be sent as the third parameter of executeFunction.

5. The Web Services and Their Functions

The NPWS groups NavigationPlanTool’s functions by scope and exposes them on four Web services. On this section you can find everything about each service.

(11)

A client has to locate the desired Web service and invoke one of its functions. The calls must be part of the code, it isn’t possible to execute a function using an NPDL command – even the execution of an NPDL command is done by calling a function. You can find suggestions for implementing clients on the Appendix.

Note: the following functions return string arrays only on the JAX-WS version of NPWS. The functions on the JAX-RPC version return long strings containing the same data. For more information, try the Javadoc on http://www.ime.usp.br/~chui/npws/doc/javadoc/jaxrpc/npws/.

5.1. The Service Commands

Name Commands

Allows To execute commands from NPDL and SQL.

WSDL File http://HOST:DOOR/NPWS/CommandsBean?wsdl

String[] execute(String commands)

> Utility

Executes one or more received commands.

> Parameters

- commands: one or more commands for execution.

> Return value

An array of strings containing:

- one element (negative value), in case of error;

- one element ("0"), if the commands were successfully executed;

- 2+(M*N) elements, if an MxN matrix of strings has been returned, where M is the first element and N is the second one. The other elements are the content of the matrix, which can be listed using the values of M and N.

5.2. The Service Processes

Name Processes

(12)

Allows To perform operations with processes.

WSDL File http://HOST:DOOR/NPWS/ProcessesBean?wsdl

String[] listProcesses()

> Utility

Lists all the defined processes.

> Return value

- one element ("0"), if there are no defined processes;

- 2+(M*3) elements, if an Mx3 matrix of strings has been returned, where M is the first element and "3" is the second one. The other elements are the content of the matrix, which can be listed using the values of M and "3". Each row of the matrix corresponds to a process and contains its ID, description and service description.

String[] getProcessInfoById(long processId)

> Utility

Returns information about a process, given its ID.

> Parameters

- processId:ID of a process.

> Return value

- four elements, in this order: "0" (successful execution), ID, description and service description.

String[] getProcessInfoByDescription(String processDescription)

> Utility

Returns information about a process, given its description.

> Parameters

- processDescription: a process' description.

(13)

> Return value

- four elements, in this order: "0" (successful execution), ID, description and service description.

long createProcessInstance(String processDescription, String clientName)

> Utility

Creates a process' instance.

> Parameters

- processDescription: description of the process to be instantiated;

- clientName: name of the instance's creator.

> Return value

A negative value, if an error occurred; otherwise, the ID of the created instance.

int removeProcessInstance(long instanceId)

> Utility

Removes a process' instance.

> Parameters

- instanceId: ID of an instance.

> Return value

A negative value, if an error occurred; otherwise, 0.

int removeProcessInstanceByProcess(long processId)

> Utility

Removes all the instances of a process.

> Parameters

- processId: ID of a process.

> Return value

(14)

5.3. The Service Instances

Name Instances

Allows To perform operations with processes’ instances.

WSDL File http://HOST:DOOR/NPWS/InstancesBean?wsdl

String[] getProcessInstanceInfo(long instanceId)

> Utility

Returns information about a process' instance.

> Parameters

> Return value

- five elements, in this order: "0" (successful execution), ID of instance, ID of process, creator's username and date when the instance was created.

String[] getProcessInstancesInfo(long processId)

> Utility

Returns information about all the instances of a process.

> Parameters

> Return value

- one element ("0"), if the process doesn't have any instance;

- 2+(M*4) elements, if an Mx4 matrix of strings has been returned, where M is the first element and "4" is the second one. The other elements are the content of the matrix, which can be listed using the values of M and "4". Each row of the matrix corresponds to an instance and contains its ID, the ID of the process, the creator's username and the date when the instance was created.

(15)

String[] getProcessesInstancesInfo()

> Utility

Returns information about all the instances of all the processes.

> Return value

String[] listProcessInstanceCurrentActions(long instanceId)

> Utility

Lists the actions of a process' instance that are available for execution.

> Parameters

> Return value

- one element ("0"), if the instance doesn't have any action that is available for execution;

- 2+(M*3) elements, if an Mx3 matrix of strings has been returned, where M is the first element and "3" is the second one. The other elements are the content of the matrix, which can be listed using the values of M and "3". Each row of the matrix corresponds to an action and contains its ID, description and execution call.

String[] listProcessInstanceCurrentRules(long instanceId)

> Utility

Lists the rules of a process' instance that are available for execution.

> Parameters

(16)

> Return value

- one element ("0"), if the instance doesn't have any rule that is available for execution;

- 2+(M*3) elements, if an Mx3 matrix of strings has been returned, where M is the first element and "3" is the second one. The other elements are the content of the matrix, which can be listed using the values of M and "3". Each row of the matrix corresponds to a rule and contains its ID, description and execution call.

String[] listProcessInstanceCurrentFunctions(long instanceId)

> Utility

Lists the functions of a process' instance that are available for execution.

> Parameters

> Return value

- one element ("0"), if the instance doesn't have any function that is available for execution;

- 2+(M*3) elements, if an Mx3 matrix of strings has been returned, where M is the first element and "3" is the second one. The other elements are the content of the matrix, which can be listed using the values of M and "3". Each row of the matrix corresponds to a function and contains its ID, description and execution call.

int isExecutionFinished(long instanceId)

> Utility

Verifies if the execution of a process' instance has been finished.

> Parameters

> Return value

A negative value, if an error occurred; otherwise, 1 if the execution has been finished or 0 if it has not.

int isCompatibleWithProcess(long instanceId, long processId)

> Utility

(17)

Verifies the compatibility between a process' instance and a process, according to the previously executed steps.

> Parameters

- instanceId: ID of an instance;

> Return value

A negative value, if an error occurred; otherwise, 1 if there's compatibility or 0 if it there's not.

int changeProcessOfInstance(long instanceId, long processId)

> Utility

Changes the process of a process' instance, since the instance is currently compatible with the new process.

> Parameters

- instanceId: ID of an instance;

> Return value

int isInstanceCancelled(long instanceId)

> Utility

Verifies if the execution of a process' instance has been cancelled.

> Parameters

> Return value

A negative value, if an error occurred; otherwise, 1 if the execution has been cancelled or 0 if it has not.

int cancelProcessInstance(long instanceId)

> Utility

Cancels the execution of a process' instance.

(18)

> Return value

int cancelStep(long stepLogId, long instanceId)

> Utility

Cancels the execution of a step using its log ID, since it's the last executed step or it's currently being executed. The effects caused by the execution aren't undone, however the step can be executed once again.

> Parameters

- stepLogId: log ID of the step to be cancelled;

> Return value

int cancelLastStep(long instanceId)

> Utility

Cancels the step with the last log ID. The effects caused by the execution aren't undone, however the step can be executed once again.

> Parameters

> Return value

int finalizeStartedActions(long instanceId)

> Utility

Finishes all the started actions of a process' instance.

> Parameters

> Return value

(19)

String[] getProcessInstanceExecutionLog(long instanceId)

> Utility

Returns the log of execution of a process' instance.

> Parameters

> Return value

- one element ("0"), if the log is empty;

- 2+(M*7) elements, if an Mx7 matrix of strings has been returned, where M is the first element and "7" is the second one. The other elements are the content of the matrix, which can be listed using the values of M and "7". Each row of the matrix corresponds to a log entry and contains log ID, step's ID, step's description, order, date when execution was started, date when it was finished and execution status.

long[] getProcessInstancesIdentifiersByCurrentStep(long stepId)

> Utility

Returns the IDs of processes' instances that contain a specific step which is currently available.

> Parameters

- stepId: ID of a step.

> Return value

An array containing one element x, x < 0, if an error occurred; otherwise, an array with one element 0 if no instances were found or an array with IDs of instances.

long[] getProcessInstancesIdentifiersByListedCurrentStep(long[] stepIds)

> Utility

Returns the IDs of processes' instances that contain a specific step which is currently available and also has its ID in the received list.

> Parameters

- stepIds: list containing IDs of steps.

(20)

> Return value

long[] getProcessInstancesIdentifiersByListedStartedStep(long[] stepIds)

> Utility

Returns the IDs of processes' instances that contain a specific step which is currently started and also has its ID in the received list.

> Parameters

> Return value

String[] getProcessInstancesInfoByStartedStep(long stepId)

> Utility

Returns information about processes' instances that contain a specific step which is currently started.

> Parameters

> Return value

String[] getProcessInstancesInfoByListedStartedStep(long[] stepIds)

> Utility

Returns information about processes' instances that contain a specific step which is currently started and also has its ID in the received list.

(21)

> Parameters

> Return value

String[] getProcessInstancesInfoByCurrentStep(long stepId)

> Utility

Returns information about processes' instances that contain a specific step which is currently available.

> Parameters

> Return value

String[] getProcessInstancesInfoByListedCurrentStep(long[] stepIds)

> Utility

Returns information about processes' instances that contain a specific step which is currently available and also has its ID in the received list.

> Parameters

(22)

> Return value

5.4. The Service Steps

Name Steps

Allows To perform operations with steps.

WSDL File http://HOST:DOOR/NPWS/StepsBean?wsdl

String[] listActions()

> Utility

Lists all the defined actions.

> Return value

- one element ("0"), if there are no defined actions;

- 2+(M*3) elements, if an Mx3 matrix of strings has been returned, where M is the first element and "3" is the second one. The other elements are the content of the matrix, which can be listed using the values of M and "3". Each row of the matrix corresponds to an action and contains its ID, description and execution call.

String[] listRules()

> Utility

Lists all the defined rules.

> Return value

(23)

- one element ("0"), if there are no defined rules;

- 2+(M*3) elements, if an Mx3 matrix of strings has been returned, where M is the first element and "3" is the second one. The other elements are the content of the matrix, which can be listed using the values of M and "3". Each row of the matrix corresponds to a rule and contains its ID, description and execution call.

String[] listFunctions()

> Utility

Lists all the defined functions.

> Return value

- one element ("0"), if there are no defined functions;

- 2+(M*3) elements, if an Mx3 matrix of strings has been returned, where M is the first element and "3" is the second one. The other elements are the content of the matrix, which can be listed using the values of M and "3". Each row of the matrix corresponds to a function and contains its ID, description and execution call.

long startActionWS(long actionId, long instanceId)

> Utility

Starts the execution of an action that's exposed as a Web service.

> Parameters

- actionId: ID of the action to be started;

> Return value

A negative value, if an error occurred; otherwise, the log ID of the started action.

long startRuleWS(long ruleId, long instanceId)

> Utility

Starts the execution of a rule that's exposed as a Web service.

> Parameters

(24)

> Return value

A negative value, if an error occurred; otherwise, the log ID of the started rule.

long startFunctionWS(long functionId, long instanceId)

> Utility

Starts the execution of a function that's exposed as a Web service.

> Parameters

- functionId: ID of the function to be started;

> Return value

A negative value, if an error occurred; otherwise, the log ID of the started function.

long executeAction(long actionId, long instanceId)

> Utility

Starts and finishes the execution of an action. The action isn't exposed as a Web service, so it should have been executed before this method was invoked. This means that this method updates database with the execution results.

> Parameters

- actionId: ID of the executed action;

> Return value

A negative value, if an error occurred; otherwise, the log ID of the executed action.

long executeRule(long ruleId, long instanceId, int bool)

> Utility

Starts and finishes the execution of a rule. The rule isn't exposed as a Web service, so it should have been executed before this method was invoked. This means that this method updates database with the execution results.

> Parameters

- ruleId: ID of the executed rule;

(25)

- bool: the execution result (1 = true, 0 = false).

> Return value

A negative value, if an error occurred; otherwise, the log ID of the executed rule.

long executeFunction(long functionId, long instanceId, int value)

> Utility

Starts and finishes the execution of a function. The function isn't exposed as a Web service, so it should have been executed before this method was invoked. This means that this method updates database with the execution results.

> Parameters

- functionId: ID of the executed function;

- value: the execution result (integer value).

> Return value

A negative value, if an error occurred; otherwise, the log ID of the executed function.

String[] getActionInfoById(long actionId)

> Utility

Returns information about an action, given its ID.

> Parameters

- actionId: ID of an action.

> Return value

- four elements, in this order: "0" (successful execution), ID, description and execution call.

String[] getActionInfoByDescription(String actionDescription)

> Utility

Returns information about an action, given its description.

> Parameters

- actionDescription: description of an action.

(26)

> Return value

String[] getRuleInfoById(long ruleId)

> Utility

Returns information about a rule.

> Parameters - ruleId: ID of a rule.

> Return value

String[] getFunctionInfoById(long functionId)

> Utility

Returns information about a function.

> Parameters

- functionId: ID of a function.

> Return value

int getNumberById(long numberId)

> Utility

Returns the value of a number.

> Parameters

- numberId: ID of a number.

> Return value

A negative value, if an error occurred; otherwise, the value of the number.

(27)

6. Identifying Errors

Errors may happen when using NPWS. For example, if a client requests information about a non-existent process, the client should be informed that the process doesn’t exist.

That’s an execution error: this kind of error corresponds to the negative values returned by the NPWS functions.

The other kind of error refers to the execution of steps which are exposed as Web services. If a service is contacted to start execution, it should report the end of execution.

When the service calls NPWS back, it’s possible that data can’t be updated or accessed: this causes an ending error.

There’s a part of NPWS which is responsible for dealing with both kinds of errors. This service is capable of storing and recovering information about them, therefore keeping clients up to date.

6.1. The Service Errors

Name Errors

Allows To recover information about execution errors and ending errors.

WSDL File http://HOST:DOOR/NPWS/ErrorsBean?wsdl

String getExecutionErrorDescription(int errorCode)

> Utility

Recovers the description of an execution error.

> Parameters

- errorCode: an integer value that corresponds to the ID of an error multiplied by -1.

> Return value

The description of the error, if found, or an error message.

String getEndingErrorDescription(long stepLogId, long instanceId)

> Utility

(28)

Recovers the description of an ending error.

> Parameters

- stepLogId: log ID of the step that couldn't be finished;

- instanceId: ID of the related process' instance.

> Return value

The description of the error, if found, or an error message.

7. Appendix

I developed the sample client with HTML and Java Servlets, therefore the XML messages exchange was implemented in Java. The applications can contact either the JAX- RPC version or the JAX-WS one, so this section contains code for both versions.

7.1. Java Code for JAX-RPC

The client uses configured dynamic invocation on a DII (Dynamic Invocation Interface) to contact the JAX-RPC-based NPWS. I found it easier than generating compiled files for static invocation, since the calls are based on WSDL files.

If a Web service doesn’t expose functions that return complex types, like arrays or matrices, the client doesn’t need to map the XML data to Java: this is automatically done.

// Establishes contact

URL wsdlUrl = new URL("http://localhost:8080/NPWS/CommandsBean?wsdl");

ServiceFactory factory = ServiceFactory.newInstance();

QName serviceName = new QName("http://endpoints/jaws", "Commands");

Service service = (Service)factory.createService(wsdlUrl, serviceName);

// Prepares the call

Call call = service.createCall();

QName operationName = new QName("http://endpoints/jaws", "execute");

call.setOperationName(operationName);

// Receives the result (command is a string)

String result = (String)call.invoke(new Object[]{command});

There are, however, cases in which there’s a function that returns a complex type, so the client must include an XML file and two additional interfaces to map that type. If a service exposes at least one function that needs mapping, all the calls have to be done with the

(29)

support of those files. Only the service Instances returns complex types (long integer arrays), so the following code doesn’t apply to the other services.

// Establishes contact

URL wsdlUrl = new URL("http://localhost:8080/NPWS/InstancesBean?wsdl");

URL mapUrl = this.getClass().getResource("/resources/jaxrpc-mapping.xml");

ServiceFactoryImpl factory = new ServiceFactoryImpl();

QName serviceName = new QName("http://endpoints/jaws", "Instances");

Service service = factory.createService(wsdlUrl, serviceName, mapUrl);

// Prepares the call

Call call = service.createCall();

operationName = new QName("http://endpoints/jaws", "isInstanceCanceled");

call.setOperationName(operationName);

// Receives the result (id is an instance of Long) int result = (Integer)call.invoke(new Object[]{id)});

The path to the XML file doesn’t need to be the same as above. For example, it could be an aside file, available on a server. And the class ServiceFactoryImpl has become deprecated since the appearance of JAX-WS.

7.1.1. Files for Clients

The Java files for using the JAX-RPC version of NPWS, as well as an instructions file, can be downloaded on http://www.ime.usp.br/~chui/npws/files/jaxrpc/client.zip.

7.2. Java Code for JAX-WS

JAX-WS made it easier to use static invocation but, on the other hand, the dynamic one has become more complex. Therefore I chose the first kind to invoke NPWS from the client. The code is always similar to the following, it doesn’t matter if the function returns or not a complex type:

Instances_Service service = new Instances_Service();

Instances inst = service.getInstancesPort();

StringArray result = inst.getProcessInstancesInfo(new Long(1));

List<String> list = result.getItem();

(30)

Just remember that the generated files have localhost as the services’ location, so there’ll be errors if the server is running on another host. To avoid this, the code is a little more complex:

URL wsdlUrl = new URL("http://<NEW_HOST>:8080/NPWS/InstancesBean?wsdl");

QName serviceName = new QName("http://endpoints.npws.ime.usp.br/", "Instances");

Instances_Service service = new Instances_Service(wsdlUrl, serviceName);

Instances inst = service.getInstancesPort();

StringArray result = inst.getProcessInstancesInfo(new Long(1));

List<String> list = result.getItem();

The classes Instances_Service and Instances help to call the service Instances, so each service has two correspondent classes. The complex types mapping is done with the classes LongArray and StringArray. When a function returns a string array, as seen above, the client has only to receive the result as an instance of StringArray and extract its content as an instance of List. The same happens to long integer arrays and LongArray. Note that the generated files deal with all the configuration (namespaces, services and calls).

7.2.1. Files for Clients

The Java files for using the JAX-WS version of NPWS, as well as an instructions file, can be downloaded on http://www.ime.usp.br/~chui/npws/files/jaxws/client.zip.

Navigation Plan for Web Services User Guide