Tutorial 01 - Create a Basic Web Service Connection

Basic Connection

The completed project is included in a resource file labeled ElandingsClient1.zip

We begin by opening up Netbeans 7.0

Click File>New Project

1. In Categorie, choose Java
2. In Projects, choose Java Application
3. Click Next

In the next screen:

1. Change the Project Name to ElandingsClient
2. Click Finish

We now have a new project called ElandingsClient

Next we wish to add web services client files automatically.

Right click on the elandingsclient package>New>Other

1. In Categories, click on Web Services
2. In File Types, click on Web Service Client
3. Click Next

In the next screen we will need to define the WSDL URL

To get the WSDL location, go to the webpage and find the WSDL URLS:

Public Facing Web Services

Choose the Test WSDL:

http://elandingstest.alaska.gov/ElectronicReportingWebServices/ReportManagementService?wsdl

1. Copy and paste the wsdl into the WSDL URL file
2. Check the Generate Dispatch code checkbox
3. Click finished

Netbeans find the WSDL and build a number of files for you and put them under "web service references". Expand the "web service references" folder to see the ReportManagementService folder and sub-folders. Netbeans created all of these files by interrogating the HTML WSDL link you provided.

Under Web Service References > ReportManagementService > ReportManagementService > ReportManagementPort, we can now see a list of the web services methods available to us.

Now we want to write some code to connect to the web service and get some data from eLandings.

We begin by creating a static reference to the web service ReportManagement object in the ElandingsClient class file.

static ReportManagement svc;

Next create a simple constructor for ELandingsClient

Public ElandingsClient(){

}

Within the constructor we want to define the ReportManagement svc object in order to connect to the WSDL. Thus far our code looks like:

import java.net.MalformedURLException;
import java.net.URL;
import javax.xml.namespace.QName;
import javax.xml.ws.BindingProvider;
import org.psmfc.er.webservices.ReportManagement;
import org.psmfc.er.webservices.ReportManagementService;

public static ReportManagement svc;

//See http://www.ibm.com/developerworks/webservices/library/ws-javaclient/
        String wsdlURL = "http://elandingstest.alaska.gov/ElectronicReportingWebServices/ReportManagementService?wsdl";
        String namespace = "http://webservices.er.psmfc.org/";
        String serviceName = "ReportManagementService";
        QName serviceQN = new QName(namespace, serviceName);

        ReportManagementService reportManagementService = new ReportManagementService(new URL(wsdlURL), serviceQN);
        svc = reportManagementService.getReportManagementPort();

//Tell the svc that it is to wait for a response from a given html location after making webservice calls.
//If we don't do this, the svc will not wait and returned results from the webservice call will not be recognized and result in an error.
        ((BindingProvider)svc).getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "http://elandingstest.alaska.gov/ElectronicReportingWebServices/ReportManagementService");

We are telling the svc object how to connect to the WSDL and then binding it to the provider. If we do not bind it to the provider, the svc object will make a request and end then what ever results the WSDL sends back will be lost. We want the svc object to be bound so that it knows it needs to wait around for the response from the WSDL.

We can get the namespace and service name from the WSDL page:

http://elandingstest.alaska.gov/ElectronicReportingWebServices/ReportManagementService?wsdl

Alternatively, we can get the wsdl url, and namespace dynamically from the generated ReportMangementService. This hides some of the details from you.

import java.net.MalformedURLException;
import java.net.URL;
import javax.naming.NamingException;
import javax.xml.namespace.QName;
import javax.xml.ws.BindingProvider;
import javax.xml.ws.WebServiceClient;

public static ReportManagement svc;

WebServiceClient a = ReportManagementService.class.getAnnotation(WebServiceClient.class);
QName serviceName = new QName(a.targetNamespace(), a.name());
URL url = new URL(a.wsdlLocation());

ReportManagementService reportManagement = new ReportManagementService(url, serviceName);
svc = reportManagement.getReportManagementPort();
((BindingProvider)svc).getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, a.wsdlLocation());

For this tutorial we will use the hardcoded approach to show you exactly what is being done. The eLandings system prefers the hardcoded approach as it is more easily integrated with properties files and multiple environments (dev, test, training and production).

Next we want to add some logic to main to create an instance of the ElandingsClient object.

public static void main(String[] args){
        System.out.println("Hello ELandings Client");
        try {
            ElandingsClient client = new ElandingsClient();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

If we run the application right now, the code should create an instance of ElandingsClient along with its webservice connection. Run it now and see that it compiles and runs as expected.

We want to create some logic to connect to the elandings webservice and ask for a users information from the elandings database.
Create a new method called connectToWebService().

public void connectToWebService() {
        try {
            String xml = svc.getUserInfo("amarx", "A_marx", "2.3");
            System.out.println(xml);

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

Now modifiy the main method to call our new method:
Next we want to add some logic to main to create an instance of the ElandingsClient object.

public static void main(String[] args){
        System.out.println("Hello ELandings Client");
        try {
            ElandingsClient client = new ElandingsClient();
            client.connectToWebService();;
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

Notice that we are calling one of the web service methods defined in the WSDL called getUserInfo(). We are passing in three arguments. Unfortunately the WSDL defines these three arguments as getUserInfo(String arg1, String arg2, String arg3). This isn¿t very helpful in explaining what values to pass into the web service method call.

To figure out the arguments, go back to the online documentation at:
Public Facing Web Services
Find the web service method that you are working with. In this case it is getUserInfo().
Open up that page to see the arguments list and some examples of those arguments listed.

The page also describes how the webservice is used in the eLandings application along with examples of when your arguments are good as well as when they are bad.

Run the application now

We can see that the web service method getUserInfo() returned a large amount of XML data associated with the eLandings user ¿amarx¿. We can see amarx's company, preferences, permits, and associated operations and vessels.