Using .

NET & Java with the Blackboard Web Services

Lance Neumann, Senior Software Architect, Blackboard Inc.

What will you learn in this session?

Brief overview of Web Services Web Services for Blackboard Learn How to get Sample Code Layout of Sample .NET projects Layout of Sample java projects Explanation of code generation scripts Build procedures Client side concepts sessions, entitlements, etc. If time permits:
Screen shots of .NET client application

Web Services overview

Essentially remote procedure calls using SOAP over HTTP Utilizes axis2 1.3 Session based authentication as User/Tool/Ticket Custom deployment/discovery to support manageability from the UI

Web Services Management

Getting the sample client code

Download from within the UI:

Will download a .zip file containing:

Sample c# .net client wrapper library Sample c# .net client application Sample java client wrapper jar Sample java client application Sample java proxy server application Sample Web Service

Readme.txt files at all levels with instructions

.NET client code layout

dotnetclient\BbWsClient : Generated client code and Sample Wrapper classes qa\dotnet\wsagent: Sample client application Key Files:
dotnetclient\readme.txt dotnetclient\sampleGenClient.cmd dotnetclient\BbWsClient\BbWsClient.csproj dotnetclient\BbWsClient\BbWsClient2008.csproj qa\dotnet\readme.txt qa\dotnet\wsagent\wsagent.csproj qa\dotnet\wsagent\wsagent.sln qa\dotnet\wsagent\wsagent2008.csproj qa\dotnet\wsagent\wsagent2008.sln

Code Generation Scripts: .NET

dotnetclient\sampleGenClient.cmd Needs access to wsdl.exe by default uses the one installed at
c:\Program Files\Microsoft SDKs\Windows\v6.0A\bin

Run in the dotnetclient directory with the base url of your Academic Suite server as a parameter:
sampleGenClient.cmd http://my.server.url

Two parts:
Code generation Code adjusting

Code Generation is merely running wsdl.exe for each of the Web Services placing the files in dotnetclient\BbWsClient\gen Note that you must have set all your Web Services as discoverable prior to generating code or this step will fail.

Code Generation Scripts: .NET

Code adjusting runs a series of sed-like replacements on the generated .cs files. These adjustments include:
Renaming duplicated classes for shared classes across Web Services to avoid build errors and ensure that all client code shares the same class definition Changing the parent class for all Web Services to Microsoft.Web.Services2.WebservicesClientProtocol to support WS-Security

A simple sed-like program is included in the .zip (bsed.exe) this is _not_ sed, but merely has enough capability to do the replacements required. If you wish to use your own sed then set SED_PATH prior to running sampleGenClient.cmd

Building: .NET
Follow the readme.txt to make sure you have the prerequisites installed (VS 2008 or 2003 and WSE 2.0) Run sampleGenClient in the dotnetclient directory to generate the client stubs Open the wsagent solution file from the qa\dotnet\wsagent directory for your VS version (.net 2003: wsagent.sln, VS 2008: wsagent2008.sln) Build and Run as normal (i.e. F5) This client application is a GUI interface to demonstrate all of the Web Service operations. It is not meant to be pretty merely functional.

Java client code layout

Client: Generated code and sample wrapper classes Javaclient: Sample client application Proxy\java: Sample proxy server application Key Files:
client\.project client\build.xml client\readme.txt client\sampleGenClient.cmd javaclient\.project javaclient\readme.txt proxy\java\.project proxy\java\build.xml proxy\java\readme.txt

Code Generation Scripts: Java

client\sampleGenClient.cmd Needs access to Axis2 1.3. By default this is d:\axis2\axis2-1.3 so set AXIS2_HOME to your axis2 installation first (See readme.txt) Needs to have sed on your path Two parts:
Code generation Code adjusting

Code Generation is merely running wsdlToJava for each of the Web Services placing the files in client\generated Note that you must have set all your Web Services as discoverable prior to generating code or this step will fail.

Code Generation Scripts: Java

Code adjusting runs a series of sed replacements on the generated .java files. These adjustments include:
Some annotations to reduce warnings in the generated code Changes to the generated ns prefixes in a number of places to avoid runtime conflicts using the default prefixes of ns1 and ns2

Building: Java
Follow the readme.txt to make sure you have all the prerequisites installed (ant, jdk, sed, axis2, rampart, eclipse) In the client directory:
Run sampleGenClient to generate the client stubs Copy project.properties to build_personal.properties and edit it to set AXIS2_HOME for your system Run ant

To build/run the javaclient application you need eclipse.

Use the Import existing projects into workspace feature and import all the .project files from the unzipped client folder. (or just client/.project and javaclient/.project) Setup the classpath variable in eclipse preferences AXIS2_HOME as per client/readme.txt Build There are several possible main classes to run here: All in com.blackboard.test.wsclient.clients.* Each of these is a relatively cryptic command line tool that tests a variety of the Web Service methods across all the Web Services.

Client Concepts: Registration

Client Concepts: Session + entitlements

Three types of sessions/methods to get a session id: User ContextWS.login
Needs userid and password only works if authentication sources is AS Internal database Session gets all the entitlements for the given user

Tool ContextWS.loginTool
Need to register the tool first, via ContextWS.registerTool Uses shared password for the tool set on the properties page for the proxy tool in AS Session only gets the entitlements for the methods requested in the earlier call to registerTool

Ticket ContextWS.loginTicket
Need to register the tool first, via ContextWS.registerTool Uses a ticket representing the currently logged in user, provided to the tool by AS during an outbound POST in response to a proxy tool action Session gets the intersection of the entitlements the user has in AS and those requested during the registerTool call

In all cases, once a session id is obtained, it must be set in the WS-Security headers for all subsequent method calls.

Client Concepts: Wrappers

Java: com.blackboard.test.wsclient.ClientWrapper - this class is the main sample wrapper code to deal with:
Creating the client stub instances Setting axis2 client options such as a callback class to handle the WS-Security headers Providing wrapper instances for the Web Services (i.e. wsclient.wrappers.*)

.net: WebserviceWrapper.cs provides similar functionality:

creates the client stub instances Sets up the usertoken on the requestsoapcontext to handle the WS-Security headers Factory for wrapper instances for the Web Services (i.e. *Wrapper.cs) Provides some wrapper calls to some of the methods on the ContextWS

.net Client Details: Main page

Conceptual Mockup: Subject to change without notice

Resources
http://www.edugarage.com/display/BBDN/How+to+Write+Basic+We b+Service+Clients Javadocs downloadable from UI for each Web Service

Questions?