Cisco Subscriber Edge Services Manager Web Services Gateway Guide 3.3
Running the Web Services Gateway Client
Download this chapter
Running the Web Services Gateway ClientRunning the Web Services Gateway Client
give_us_feedback

Table Of Contents

Web Services Gateway Client

Using Web Services Clients

Client Code

Generating the Client Code

Using the Generated Client Code

Using the Axis WSG Stubs

Required Classes

Axis Initialization

Stub Initialization

Using the WSG Stub

Running the Client Interface for the Web Services Gateway

Starting the WSG Client

WSG Client Command Examples

Setting the Host

Authenticating a User

Activating and Deactivating a Service

Ending a WSG Client Session


Web Services Gateway Client

This appendix describes how to use the Web Services Gateway Client and the client interface that provides command-line access to the Web Services Gateway (WSG). This appendix contains the following sections:

•Using Web Services Clients

•Running the Client Interface for the Web Services Gateway

Using Web Services Clients

SESM provides a WSG client application which is useful for testing the WSG applications.

Any client application can interface with the WSGs using the Simple Object Access Protocol (SOAP) over HTTP. SOAP allows disparate technologies to be used to implement client and server technologies. The SESM WSG provides a service that has been implemented in Java. However web services clients may be implemented in any programming language that supports SOAP over the HTTP standard.

This is achieved by using the decoupled SOAP protocol for the interface to the WSG. This SESM WSG interface is described in the Web Services Description Language (WSDL). This description can be used to generate client code in a programming language of the users' choice.

The client code generated from the WSDL translates the SESM WSG calls from the client's native programming language into standardized SOAP messages and sends them to the WSG over the HTTP protocol. The client code also receives the responses from the WSG and translates the standard SOAP messages back to the client's programming language.

The SESM WSG uses the apache Axis 1.1 implementation of SOAP, which supports bindings to the Java, C and C++ languages. (For details on Axis implementation of SOAP see the Apache web site) You may use other implementations of SOAP to generate the client code if other programming languages or environments are required (e.g..NET).

Note You may face interoperability problems when using client implementations other than Axis 1.1 as SOAP is an emerging standard. If such problems are encountered please contact your Cisco support representative for the latest updates.

Implementing a web services client using WSDL involves the following tasks:

•Generate client stubs from WSDL.

•Compile client stubs.

•Write client application using the client stubs.

•Link and execute client application + client stubs + axis runtime libraries.

Note Some environments, for example .Net, may automate all or part of this process.

Client Code

Typically two types of code need to be generated from the WSDL for use by the client application programmer. These are the interface types and stubs. An interface type is a data structure that is sent and received over the SOAP protocol bound to the clients programming language. For example, the WSG WSDL defines the type Identity in the WSDL as follows: 

<complexType name="Identity" 

          <sequence   

            <!-- The type of the identity. -- 

          <!-- Known values are: "IP Address", "MAC Address", 

  "VPI/VCI" -- 

            <!-- "SSG sub interface", "user name" and "msisdn" -- 

            <element name="type" nillable="false" 

  type="soapenc:string"/ 

            <!-- The value of the identity. -- 

            <element name="principal" nillable="false" 

  type="soapenc:string"/ 

          </sequence 

        </complexType

If C is the client programming language, then a C strut is generated to hold the data of an Identity and to allow it to be passed to and from the interface: 

typedef struct IdentityTag {

          xsd__string type;

          xsd__string principal;

      } Identity;

If C++ is the client programming language, the a class is generated instead of the structure: 

class Identity

     {

       public:

          xsd__string type;

          xsd__string principal;

          Identity();

          ~Identity();

     };

The code associated with this class declaration is also generated. Likewise if the client programming language is Java, then a java class is generated to hold the same data: 

public class Identity  implements java.io.Serializable {

      private java.lang.String type;

      private java.lang.String principal;

      public Identity() {}

      public java.lang.String getType() { return type; }

      public void setType(java.lang.String type) { this.type = type; }

      public java.lang.String getPrincipal() { return principal; }

      public void setPrincipal(java.lang.String principal) { 

  this.principal = principal; }

      // ... plus static utitity methods

    }

In addition to the interface types, the interface stubs are also generated. A stub is a programming interface that appears like the interface defined in the WSDL, but instead of providing an implementation of the actual behavior, the stub implementation uses SOAP to communicate with the real implementation on the WSG server. In both C++ and Java, the generated stub is an interface with a signature derived from the WSDL and a class that implements that interface.

The generated interface in C++ is: 

class SESM

    {

      private:

          Call* m_pCall;

      public:

          SESM();

          virtual ~SESM();

          void authenticate(xsd__string Value0,Credential_Array 

  Value1,xsd__boolean Value2);

          void endSession(xsd__string Value0);

          void getStatus(xsd__string Value0,Status* Value1);

          void serviceActivate(xsd__string Value0,xsd__string 

  Value1,Credential_Array Value2,xsd__boolean Value3);

          void serviceDeactivate(xsd__string Value0,xsd__string Value1);

    };

The generated interface in Java is: 

public interface SESM extends Remote 

    {

      public boolean authenticate(String hostkey, Credential[] 

  credentials) throws RemoteException;

      public void endSession(String hostkey) throws RemoteException;

      public Status getStatus(java.lang.String hostkey) throws 

  RemoteException;

      public boolean serviceActivate(String hostkey, String 

  service, Credential[] credentials) throws RemoteException;

      public void serviceDeactivate(String hostkey, String 

  service) throws RemoteException;

    }

If the client language is C, then functions are defined and implemented for each interface method: 

extern void authenticate(void* pStub, xsd__string Value0, 

  Credential_Array Value1, xsd__boolean Value2);

    extern void endSession(void* pStub, xsd__string Value0);

    extern void getStatus(void* pStub, xsd__string Value0, 

  Status* Value1);

    extern void serviceActivate(void* pStub, xsd__string 

  Value0, xsd__string Value1, Credential_Array Value2, 

  xsd__boolean Value3);

    extern void serviceDeactivate(void* pStub, xsd__string 

  Value0, xsd__string Value1);

Generating the Client Code

To generate interface types and stubs, implementation of SOAP provides utility programs that read the WSDL and generate the required files for both the server side and the client side.

For the Axis 1.1 SOAP implementation, this utility is a java class: org.apache.axis.wsdl.WSDL2Java that generates java stubs and org.apache.axis.wsdl.wsdl2ws.WSDL2Ws. To run these utilities, the java classpath must be set to include the jar files indicated by Axis documentation.

Note Currently, versions later than Axis 1.1 do not generate C++ code correctly.

The types and stubs may then be generated with the following commands:

Client Type
Command

C clients

java org.apache.axis.wsdl.wsdl2ws.WSDL2Ws sesm.wsdl -lc -sclient

C++ clients

java org.apache.axis.wsdl.wsdl2ws.WSDL2Ws sesm.wsdl -lc++ -sclient


Java clients

java org.apache.axis.wsdl.WSDL2Java sesm.wsdl



See "Web Services Gateway Interface" for information about the sesm.wsdl file, which provides a description of the WSG interface distributed with SESM.

Note In order to generate code in C or C++, you must uncomment the service definition section at the end of the sesm.wsdl file.

Using the Generated Client Code

Each SOAP implementation is different in how its generated stubs are to be used by application developers. Refer appropriate documentation for details. However, all implementations follow the same basic steps:

•Initialize the SOAP runtime and configure the SOAP transport.

•Create the stub instance.

•Bind the stub instance to a URL defining the location of the service.

•Set any additional transport authenticate/security properties.

•Use the stub instance.

Using java as an example language, the following code creates a SESM stub and calls the authenticate method. 

// Initialize the SOAP runtime and configure the SOAP transport

          EngineConfiguration defaultConfig = 

  EngineConfigurationFactoryFinder.newFactory().getClientEngineConfig();

          SimpleProvider config = new SimpleProvider(defaultConfig);

          SimpleTargetedChain c = new SimpleTargetedChain(new 

  org.apache.axis.transport.http.HTTPSender());

          config.deployTransport("http", c);

          Service service = new Service(config);

          // create the stub instance and bind to URL

          String endpointURL="http://wsghost:8080/services/SESM";

          SESM sesm = new SesmSoapBindingStub(endpointURL,service);

          // Configure authentication

          ((SesmSoapBindingStub)sesm).setUsername(service_username);

          ((SesmSoapBindingStub)sesm).setPassword(service_password);

          // use the stub instance

          Identity id = new Identity();

          id.setType(IdentityType.USER.toString());

          id.setPrincipal(user_username);

          Credential[] creds = {new Credential()};

          creds[0].setIdentity(id);

          creds[0].setCredential(user_password);

          sesm.authenticate(user_hostkey,creds));

Using the Axis WSG Stubs

The SESM solution contains java stubs of the WSG interface that have been generated from the SESM WSDL. These stubs may be used by a client program written in Java to access the WSG. The stubs are generated by Axis 1.1. Axis documentation should be consulted for the full reference on using these stubs.

Required Classes

The client code needs to import the following classes generated by Axis: 

import com.cisco.sesm.wsg.common.Credential;

import com.cisco.sesm.wsg.common.Identity;

import com.cisco.sesm.wsg.common.ServiceStatus;

import com.cisco.sesm.wsg.common.SesmSoapBindingStub;

import com.cisco.sesm.wsg.common.Status;

These classes are contained within the com.cisco.sesm.wsg.jar file which must be on the CLASSPATH of the java compiler and the java runtime for the client.

The following Axis classes are also needed: 

import org.apache.axis.EngineConfiguration;

import org.apache.axis.SimpleTargetedChain;

import org.apache.axis.client.Service;

import org.apache.axis.configuration.EngineConfigurationFactoryFinder;

import org.apache.axis.configuration.SimpleProvider;

import org.apache.axis.Handler;

These classes are contained in the axis.jar file from apache, which also must be available on the CLASSPATH of the java compiler and the java runtime for the client.

To run the client, the following jars (bundled with Axis) must also be on the CLASSPATH:

•commons-discovery.jar.

•commons-logging.jar.

•jaxrpc.jar.

•mail.jar.

•saaj.jar.

•wsdl4j.jar.

Axis Initialization

In order to use an Axis generated stub, the Axis runtime service and transport must be initialized. For full details of this, see the Axis documentation.

The following code initializes the Axis service: 

// Setup configuration for AxisClient

   EngineConfiguration defaultConfig = 

  EngineConfigurationFactoryFinder.newFactory().getClientEngineConfig();

   SimpleProvider config = new SimpleProvider(defaultConfig);

   SimpleTargetedChain c = 

     new SimpleTargetedChain(new 

  org.apache.axis.transport.http.HTTPSender());

   config.deployTransport("http", c);               

   Service service = new Service(config);

This configuration uses the default Axis HTTP transport, which is a simple HTTP client using non-persistent connections. The com.cisco.sesm.wsg.jar bundles an alternative HTTP transport that uses the JVM's URLConnection class, which may use persistent connections and other more efficient techniques.

This alternative transport can be used by replacing the org.apache.axis.transport.http.HTTPSender class in the code above with org.apache.axis.transport.http.HttpURLConnectionSender. Alternative transports are also available from Axis and other sources that use the Jakarta HttpClient transport.

Stub Initialization

Once the axis service is initialized, an instance of the SESM WSG stub can be created and initialized with the following code: 

     sesm = new SesmSoapBindingStub(endpointURL,service);

     sesm.setUsername(username);

     sesm.setPassword(password);

The endpointURL is a string URL that gives the location of the SESM WSG server. Examples of non-SSL and SSL endpoint URLs are:

http://sesmhost:8100/services/SESM

https://sesmhost:8463/services/SESM

The username and password set here are not those of the actual SESM users. Rather they are a username and password that has been allocated to the WSG client itself so that it can authenticate with the SESM WSG service. See Configuring WSG Authentication for information on configuring these usernames and passwords.

Typically a single instance of the SESM WSG stub class will be used by a WSG client and requests for multiple users will be sent over the shared instance.

For optimum throughput, the number of user requests that share a single sesm stub instance should be limited. This limit needs to be determined by benchmarking the actual hardware and server used with realistic requests.

Using the WSG Stub

Once initialized, the WSG stub instance may be used to make calls on the WSG server as it is a local class to the client. To make some WSG calls, the generated data type classes must be created and/or decoded. For example the following code creates an authentication request for a given hostkey, username and password: 

public void authenticate(SESM sesm, String hostkey, String 

 username, String password)

    throws RemoteException

  {

      Identity id = new Identity();

      id.setType("user");

      id.setPrincipal(username);

      Credential[] credential = {new Credential()};

      credential[0].setIdentity(id);

     credential[0].setCredential(password);


      sesm.authenticate(hostkey,credential);

   }

This code will either succeed in authenticating the user for the given hostkey, or it will throw a RemoteException, which will wrap the real exception that should explain the cause of the failure. The wrapped exception may be retrieved with the getCause() method of RemoteException.

The following code illustrates how the getStatus method can be called and the resulting information displayed on stdout: 

      public void getStatus(SESM sesm, String hostkey)

          throws RemoteException

      {

          System.out.println("Status of "+hostkey+":");

          // get the status of the host key;

          Status status = sesm.getStatus(hostkey);

          if (status != null)

          {

            // report on all identities for hostkey

            Identity[] ids = status.getIdentities();

            for(int i=0; ids!=null && i<ids.length; i++)

              System.out.println(" Identity 

  "+ids[i].getType()+": "+ids[i].getPrincipal());

            // report on all services for hostkey

            ServiceStatus[] statii = status.getServices();

            for(int i=0; statii!=null && i<statii.length; i++)

            {

              System.out.print("Service "+statii[i].getService());

              if (statii[i].isActive()) 

              {

                 System.out.print(": ON ");

                 ids = statii[i].getServiceIdentities();

                 char s='(';

                 for(int j=0; ids!=null && j<ids.length; j++)

                 {

  System.out.print(s+ids[j].getType()+":"+ids[j].getPrincipal());

                    s=',';

                 }

                 System.out.print(") 

  time="+statii[i].getTimeConnected());

                 System.out.print(" b2u="+statii[i].getBytesToUser());

                 System.out.print(" 

  b2s="+statii[i].getBytesToService());

                 System.out.print(" p2u="+statii[i].getPacketsToUser());

                 System.out.println(" 

  p2s="+statii[i].getPacketsToService());

               }

               else

                 System.out.println(": off");

             }

           }

         }

      }

Running the Client Interface for the Web Services Gateway

The WSG client application is useful for testing the WSG applications. You can activate commands with the client that will communicate with WSG. The client interface provides a command-line interface for interacting with the WSG using SOAP remote procedure calls (RPC).

This interface is intended to demonstrate and test the functionality of the WSG. In order to deploy the WSG, you must develop your own SOAP client interface to replace the demonstration client interface.

The demonstration client interface script is located in here: 

wsg

bin

wsgClient

Starting the WSG Client

To start the WSG client, perform the following procedure:

Step 1 Enter: 

wsgClient [endpoint]

Where endpoint is either 

http://WSGhost:8100/services/SESM

To connect using a non-secure port.

or 

https://WSGhost:8463/services/SESM

To connect using a secure port.

Step 2 At the prompt enter a user name and password for basic authentication between the WSG client and the WSG server. 

WSG Username:

The default user name is wsg. 

WSG Password:

The default password is wsg.

Note To disable authentication from the WSG client startup, see Disabling WSG Authentication.

Once you have been authenticated, the WSG client command-line prompt is displayed: 

wsg>

At the prompt, enter help to display available commands. At subsequent prompts, enter any of the commands listed in Table A-1.

Table A-1 The Web Services Gateway Client Commands

Command
Description

auth

Authenticates the user request, and then creates a user's host object on the SSG from data stored in the Security Policy Engine (SPE) or RADIUS. This information contains the user's shape, including username, host-id, and the services to which the user is subscribed.

get

Gets a host object from SPE after user authentication.

act

Activates or reactivates a service in a user's host-id. For example, the command
act iptv - - activates iptv service with no username or password.

dea

Deactivates a service from a user's host-id. For example, the command dea iptv deactivates iptv service.

end

Ends a session by removing the host object from the SSG.

host

Sets the host key.

h

Displays help information.

fork n

Run the remainder of the command line n times in parallel.

loop n

Run the remainder of the command line n times in series.

close

Close the command line input so that client exits at the end of test.

query

Query the state of the host key session.


WSG Client Command Examples

This section provides examples of the WSG commands and their output.

Setting the Host

Use the host or hostkey command to set the IP address and port number of the WSG client.

Setting the Hostkey for an IP Address Host Key Session

Step 1 Use the hostkey command to set the host for an IP address host key session: 

wsg> hostkey subscriber_IP_address

The SSG must be able to route this IP address through a configured downlink interface when it creates the edge session for the subscriber.

For example: 

wsg> hostkey 209.165.200.225

hostkey=209.165.200.225

Step 2 Use the hostkey % command to set a random host key.

Setting the Host for a Port-Bundle Host Key Session

Step 1 Obtain hostkey information from the SSG, as follows:

To get the IP address map of the subscriber from the SSG, use the following command: 

ssg>show ssg host

1: 64.103.64.210  [Host-Key 1.1.1.5:65]

In this example, the IP address map of the host key is 1.1.1.5 and the port bundle is 65.

Step 2 Get the port number that the SSG has mapped to the subscriber, using the ssg port-map command with the parameters that were returned by the show ssg host command.

For example: 

ssg>sh ssg port-map ip 1.1.1.5 port 65

State = IN-USE

Subscriber Address = 64.103.64.210

Downlink Interface = FastEthernet1/0


Port-mappings: -


Subscriber Port:    2257                Mapped Port:    1040

In this example, the mapped port for the subscriber is 1040.

Step 3 Set the host for a Port-Bundle Host Key(PBHK) session on the WSG session as follows once you have the IP address map and the port map information you can: 

wsg> host IP_address_map/port_map

For example: 

wsg> host 1.1.1.5/1040

hostkey = 1.1.1.5/1040

Authenticating a User

Use the auth command to authenticate the subscriber with the SSG. 

wsg> auth username password

For example: 

wsg> auth golduser cisco 

authenticate=true

Use the auth % cisco command to authenticate a random user 0 to user 45.


Activating and Deactivating a Service

Use the get command to display the status of the user account and the services the user is currently subscribed to. The following parameters are provided for each active service:

•time—time that the service has been active for the session (in seconds).

•b2u—number of bytes sent downstream for the session.

•b2s—number of bytes sent upstream for the session.

•p2u—number of packets sent downstream for the session.

•p2s—number of packets sent upstream for the session.

For example: 

wsg> get

Identity user: golduser

Service games: off

Service dynamic_bandwidth_selection: off

Service Internet-Basic: off

Service discount_shopping: off

Service Internet-Premium: ON (user:) time=625 b2u=5238 b2s=1020 p2u=56 p2s=22


Service corporate: off

Service Internet-Standard: off

Use the dea command to deactivate a service. For example: 

wsg> dea Internet-Premium 

deactivate Internet-Premium

Use the get command to verify that the service was deactivated. For example: 

wsg> get

Identity user: golduser

.

.

.

Service Internet-Premium: off

Use the act command to activate the service. For example: 

wsg> act Internet-Premium 

activate Internet-Premium = true

Use the get command to verify that the service was reactivated. For example: 

wsg> get

Identity user: golduser

.

.

.

Service Internet-Premium: ON (user:) time=625 b2u=5238 b2s=1020 p2u=56 p2s=22

Ending a WSG Client Session

Use the end command to end the current session and use the quit command to exit the shell. 

wsg> end

endSession

wsg> quit

user1>