The Blackboard Learn SOAP Web Services come out of the box with sample code that can be downloaded directly from the user interface. This document will describe the process by which a developer can build the java client library contained within that code.
The file that you download from Learn containing all of the sample code is called client.zip, so when you unzip it, it will be called client. This is referred to as the top-level client directory in this document. This document specifically deals with a subfolder of that directory, which is also called client. When top-level client directory is specified, this refers to /path/client. When top-level is not specified, it refers to /path/client/client.
Preparing the Development Environment
This sample code was initially built when Blackboard Learn 9.1 was released several years ago. As a result, it is dependent upon some older technology. It is suggested that the technologies installed for this tutorial be segmented for this purpose.
|SED||If building on Windows, you must install sed, either stand-alone, or from cygwin|
|Java||Script tested on Java 7, should work with Java 8|
|Axis2 1.3 Source|
In order to set the development environment up with these technologies without overriding newer versions that may be being used in other projects, it is recommended that a separate directory be set up in the top-level client directory and environment variables be temporarily pointed to them. In this example, a tools directory has been added to the client directory, an Ant, Axis, and Rampart were unzipped here.
Now open a terminal or cmd window, and navigate to the client directory, by typing: cd <pathtodirectory>/client/client and pressing <ENTER>. You should now be in the client directory.
We will need three environment variables to be set: JAVA_HOME, AXIS2_HOME, ANT_HOME. JAVA_HOME should be set to point to your JDK installation. This is probably already set. To verify, type: echo $JAVA_HOME and press <ENTER>. AXIS2_HOME, should be set to the path to Axis 2 where you just installed it. In our example, it would be client/tools/axis2-1.3. Lastly, ANT_HOME should be set to the Ant directory you just installed. In this example, ANT_HOME would be set equal to client/tools/apache-ant-1.6.0.
The next step is to configure axis2 for building the sample code. To do this, we must copy a few files from rampart, and modify one file. In our example, we would copy all the jar files in client/tools/rampart-1.4/lib to client/tools/axis2-1.3/lib. Then we must copy client/tools/rampart-1.4/modules/rampart-1.4.mar to client/tools/axis2-1.3/repository/modules directory. In the same directory you copied the mar file to, there is a file called modules.list. You must edit this file and add rampart-1.4.mar to the bottom of the list and save it. The last step is optional, and that is to create a subdirectory to axis2-1.3 called src, and download the axis2 source here. This is not required for the build to work, but if you will be debugging your code in Eclipse, this will allow you to follow the code into Axis2.
Now your development environment is all set to generate the code and build the Java Web Services Library.
Building the Library
The first step is to generate the code. This is done at the command line and in the client/client directory. Simply run sampleGenClient.[cmd|sh] http://<your learn server>. There are two caveats here. Firstly, if you are running this on Mac or Linux, the sampleGenClient.sh file contains Windows ctrl-M line endings. This will cause the script to fail. The easiest way to fix this is to use sed (sed -e "s/^M//" sampleGenClient.sh > sampleGenClient1.sh). Please note that the ^M actually refers to the control character, so to enter, you will need to hold down the ctrl key and press v and then m. The second caveat is that this file will fail if you use https:// and building against a self-signed certificate like the Developer Virtual Machine. Just use http://.
You will now end up with a generated-src directory. You can build the library using ant, by simply typing $ANT_HOME/bin/ant build and pressing <ENTER>. You will now have client/client/lib/wsc.client.jar.