To show how a client application connects to the server, this section uses the source code for the wsclient.bat batch file to illustrate concepts. Also, the Java source code that enables wsclient.bat makes calls to the Apache Axis toolkit methods; if you are not using Apache Axis, map these methods to ones used by your Web services methods.
The wsclient.bat batch file is implemented using the methods located in the WSClient.java file, as mentioned in the section describing sample clients (Section 1.1.1, Sample Clients). This file contains the fetch method, which is a wrapper that performs most of the direct calls to the Apache Axis toolkit methods, which in turn make the call to Web services. In summary, the fetch method connects the wsclient.bat client to the server, sets up the remote procedure calls, names the operation, and invokes the passing of messages using Web services.
This section describes step-by-step the initial lines of code in the fetch method to show how to connect your client to the server. Consider these initial lines of code:
// Replace the hostname in the endpoint appropriately.String endpoint = "http://localhost:8080/ssf/ws/Facade";
The wsclient.bat file is designed to be executed on the same machine that runs the Novell Teaming installation. Many client applications connect to the server from another machine on the Internet. Provide the appropriate host and port for the Novell Teaming server to which you want to connect.
Consider the next lines of code:
// Make sure that...client_deploy.wsdd...is accessible to the program.EngineConfiguration config = new FileProvider("client_deploy.wsdd");
.
.
.
call.setProperty(WSHandlerConstants.USER, "admin");
As required by the source code for the client, the client_deploy.wsdd file is located in the same directory as the wsclient.bat file. It contains XML needed by Apache Axis to implement security. It establishes a username that a client can use as its persona when working with Web services (by default, it is the admin account). It also points to two other files used by Apache Axis as part of the way it implements security:
PWCallbackDigest.java
PWCallbackText.java
A subsection that follows provides helpful notes about security choices for your client application (Section 1.2.1, Notes About Security).
For example, the wsclient.bat client uses the persona of the adminNovell Teaming account. To specify the password for this persona, the PWCallbackText.java file contains these lines, which set the password to test:
if ("admin".equals(id)) { pc.setPassword("test");}
The call to the call.setProperty method establishes a constant that specifies the admin account as being the persona to be used by the client. It is rare that a client uses the same persona for all its work on the server.
Remember that this way of establishing a persona for your client software is specific to Apache Axis. If you are not using Apache Axis, use these examples to inform the work with your Web services toolkit.
These lines of code are the remaining ones required by Apache Axis to set up and then make the call to the server:
Service service = new Service(config);Call call = (Call) service.createCall();call.setTargetEndpointAddress(new URL(endpoint));// We are going to invoke the remote operation to fetch the workspace// or folder to print.call.setOperationName(new QName(operation));// Programmatically set the username. Alternatively you can specify// the username in the WS deployment descriptor client_deploy.wsdd// if the username is known at deployment time and does not change// between calls, which is rarely the case in Aspen.call.setProperty(WSHandlerConstants.USER, "admin"); if(filename != null) { DataHandler dhSource = new DataHandler(new FileDataSource(new File(filename))); call.addAttachmentPart(dhSource); //Add the file. call.setProperty(Call.ATTACHMENT_ENCAPSULATION_FORMAT, Call.ATTACHMENT_ENCAPSULATION_FORMAT_DIME);} //End of if Object result = call.invoke(args);
.
.
.
Your client application can implement security in several ways. Each method has advantages and disadvantages, which you should consider. This section contains the following subsections, in order from the most secure to the least secure:
On the client side of the Web services transaction, the client code provides a username and password, and the Web services security framework digests the password and sends it to the server.
On the server side, Novell Teaming retrieves the user’s password from its database and passes it to the Web services security framework.
One of the disadvantages to this method of implementing security is that, because Novell Teaming stores the password in encrypted form, it cannot pass a clear-text password to the framework for comparison. To solve this problem, before digest and transmission, the client can use the Novell Teaming password-encryptor class to apply the same encryptor to the clear-text password and can then pass the encrypted password to the security framework.
So, although secure, this method requires work on the client side.
On the client side of the Web services transaction, the client code provides a username and password to the Web services security framework, and the framework passes the password as plain text.
On the server side, the security framework allows Novell Teaming to retrieve the clear-text password from the message using an application programming interface (API) call. When retrieved, Novell Teaming applies its internal password encryptor and compares the result with the password stored in the database for the user. Novell Teaming performs the authentication; if successful, Novell Teaming returns the clear-text password to the Web services security framework to complete its process.
The primary disadvantage of this method is that it is not secure unless it’s being done using SSL. Another disadvantage is that, if the password does not match, Novell Teaming must throw an exception in order to cause the security framework to abort its process. (This problem with mismatching passwords does not occur using Password Digest.)
So, this method is easier to code on the client side, but it has several disadvantages.