Best Practices and Guidelines for WS Usage

Handling Errors

When using the WS API with a remote instance, there may be time out issues or fails from time to time. To deal with those errors and recover from them when using the client, handle the exception without throwing. You need to highlight the catch clause when adding the Service using the ServiceManager. This is useful when adding services using the API when some fail. Handling the exception helps keep track of which parts failed, so they can be re-added in a reliable manner. E.g., when adding 1000 services, some fail in the loop. Adding those that got missed can be done by keeping track of the exceptions.

Avoiding Timeouts

Make sure that the logged in session does not timeout when adding elements via the API for a prolonged time by using the following two steps:

Set the client timeout to a defined value (by default this is 100000). Following code where we set a client timeout using WSRegistryServiceClient when initializing. Check the following code.
```
new WSRegistryServiceClient(serverURL, username, password, clientTimeoutInMilliSeconds ,configContext);
```
Log in to the server again if the time elapsed from the last login is greater than the timeout value - marginalTime, which should be greater than one execution time of the loop. Here is the code.
```
if ((System.currentTimeMillis() - startingTime) >= (clientTimeoutInMilliSeconds - marginalTime)) 
{
	System.out.println("Session timed out login again");
	registry = initialize();
}
```
This code can be used to add artifacts without session timeout interruption.

Logging Out

If you wish to log out once you're done, use the logout method in WSRegistryServiceClient. The following code can be used to log out:

((WSRegistryServiceClient)registry).logut();

Here we need to cast the registry object to the WSRegistryServiceClient in order to do that.

Sample Details

The full sample can be found in $CARBON_HOME/samples/ws-client and the class on the SVN can be found here.