1. Web Services and Blackboard
Bob Alcorn
Blackboard, Inc.

2. And now a word from our lawyers…
Any statements in this presentation about future expectations, plans and prospects for Blackboard and other statements containing the words "believes," "anticipates," "plans," "expects," "will," and similar expressions, constitute forward-looking statements within the meaning of The Private Securities Litigation Reform Act of Actual results may differ materially from those indicated by such forward-looking statements as a result of various important factors, including the factors discussed in the "Risk Factors" section of our most recent 10-K filed with the SEC. In addition, the forward-looking statements included in this press release represent the Company's views as of April 11, The Company anticipates that subsequent events and developments will cause the Company's views to change. However, while the Company may elect to update these forward-looking statements at some point in the future, the Company specifically disclaims any obligation to do so. These forward-looking statements should not be relied upon as representing the Company's views as of any date subsequent to April 11, Blackboard, in its sole discretion, may delay or cancel the release of any product or functionality described in this presentation.

3. Overview Web Services Overview
High-level, not a detailed tutorial
Relationship to Blackboard Building Blocks™
Consuming Web Services
Creating Web Services

4. Audience Familiarity with Java Servlet programming
Familiarity with HTTP
Experience with Blackboard Building Blocks

5. Overview – Web Services
Collection of inter-related technologies
SOAP. The basic protocol semantics. “…definition of the XML-based information which can be used for exchanging structured and typed information between peers in a decentralized, distributed environment.”
XML Schema. Type system for SOAP.
UDDI. Service discovery.
WSDL. Service description.
In a nutshell, XML encoded method calls over HTTP

6. Web Services and Blackboard Building Blocks
Perfect fit for heterogeneous computing…
Client to server, Server to server
Easy to understand and analyze
Well-supported
Blackboard® application can be either consumer or producer
Ideal model for “standalone” programs

7. Web Services and Blackboard Building Blocks
Consumer
Add “call out” capability to your extensions
Producer
Expose your methods via Web Services

8. Web Services and Blackboard Building Blocks
Freely available Java-based toolkits
Axis (formerly IBM soap4j)
Sun Web Services Developer Kit
Other vendor solutions…
Maps perfectly to deployment model
Toolkits designed for deployment in web apps

9. Web Services and Blackboard Building Blocks
Blackboard Building Block deployment model has some unique advantages
Different extensions can implement their own Web Services… identical names
Axis can exist in multiple webapps, even with different versions

10. Challenges in Existing Architecture
Session Management
Assumes stateful, browser-oriented clients
Cookie redirect
Authentication
SOAP standards mute on credentials
Authentication APIs not generalized enough…
Authentication APIs not specific enough…

11. Web Services – Technical Issues
API Granularity
Calls are expensive, incorporating the overhead of
XML serialization
Network (HTTP) communication
XML de-serialization
…and back again

12. Doing it Today…
Blackboard Learning System™ App Pack 1 and higher incorporate .NET/CLR code for both API layer data access and Web Services (via .asmx)
Gain the benefits of CLR, ease of development with .NET tools
Extensions can also package Java-based Web Services tool of choice
Local to web application
E.g., Apache Axis

13. Using Web Services Get Some WSDL Provided by the Web Service Generate
Stubs
E.g., wsdl2java
Write code
Using Stubs
The code you write
Package
Webapp
The standard B2 packaging
Deploy to
Blackboard

14. Configuration Standard Blackboard Building Block configuration
bb-manifest.xml
web.xml
Requires outgoing socket connection permission
<permission type=“socket” name=“api.google.com” actions=“connect”/>

15. Configuration – Gotcha!
client-config.wsdd must be readable by the extension (e.g., WEB-INF)
Set property first!

16. Configuration – Gotcha!
You must declare additional permissions
RuntimePermission, accessDeclaredMembers
PropertyPermission, javax.wsdl.factory.WSDLFactory, write
RuntimePermission, getClassLoader
RuntimePermission, createClassLoader

17. Example Find a service to consume
MERLOT Web Search Service
Use WSDL to generate Java stub classes
Wsdl2java – Takes a .wsdl file (or URL) and generates stub classes
Can be invoked via an Ant task…

18. Generating Stubs For typed invocation Axis – IBM wsdl4j
Makes it easy to work within your language of choice; data mapped to language objects
Dynamic invocation also supported by most toolkits
Axis – IBM wsdl4j
Ant task

19. Generating Stubs – Ant Task
<path id="axis.classpath">
<fileset dir="${axis.home}/lib">
<include name="**/*.jar"/>
</fileset>
</path>
<taskdef resource="axis-tasks.properties" classpathref="axis.classpath"/>

20. Generating Stubs – Ant Task
<axis-wsdl2java output="src“ verbose="true“ url=“${merlot.wsdl}”>
<mapping namespace=" package="blackboard.client"/>
<mapping namespace=" package="blackboard.client"/>
</axis-wsdl2java>

21. Example – Permissions <permissions> <permission . . . />
<permission type="socket" name=“matanzas.merlot.org" actions="connect,resolve"/>
<permission type="runtime" name="accessDeclaredMembers" actions=""/>
<permission type="java.util.PropertyPermission" name="java.protocol.handler.pkgs" actions="write"/>
</permissions>

22. Example – Using the Stubs
String queryTerms = request.getParameter("queryTerms");
//get config file
String fileName = getServletContext().getRealPath( "/WEB-INF/client-config.wsdd" );
AxisProperties.setProperty( EngineConfigurationFactoryDefault.OPTION_CLIENT_CONFIG_FILE, fileName );
GoogleSearchServiceLocator locator = new GoogleSearchServiceLocator();
GoogleSearchPort googleSearch = locator.getGoogleSearchPort();
GoogleSearchResult result = googleSearch.doGoogleSearch( );
elements = result.getResultElements();
request.setAttribute( Constants.RESULTS_KEY, Arrays.asList( elements ) );
. . .

23. Checklist Axis libraries client-config.wsdd Stub generator/stubs
Client class with configuration to bootstrap properties
Manifest with correct permissions

24. .NET APIs and Web Services
CLR APIs introduced in Blackboard Academic Suite™ version used to expose basic Web Services, via ASP.NET
Methods correspond to loaders/persisters in APIs
Windows only

25. Using .NET API Web Services
Example using Java
Generate stubs
AnnouncementWebService.asmx?wsdl
Implement authentication
Currently only supports Blackboard authentication
Credentials passed via SOAP header

26. Using .NET Web Services
BbAnnouncementWSSoapStub webService = (BbAnnouncementWSSoapStub) newBbAnnouncementWSLocator().getBbAnnouncementWSSoap();
String passHash = webService.getMD5Hash( PASSWORD );
SOAPHeaderElement authHeader = new SOAPHeaderElement( null, "BbAuthentication" );
authHeader.addChildElement( "bbUser" ) .addTextNode( "administrator" );
authHeader.addChildElement( "bbPassword" ) .addTextNode( passHash );
authHeader.addChildElement( "bbAuthenticationType" );
webService.setHeader( authHeader );
Announcement[] list = webService.loadByCourseId( courseId ) .getAnnouncement();

27. Generating Web Services
Decide on the methods you want to support
“Chunky” is better; return a lot of data in few calls
Create Java classes that implement the interface

28. Web Service Class public class CourseManager {
public CourseWrapper[] getCourseList( String userName ) {
//… work goes here }

29. Axis Tasks Implement Class
Configure Axis deployment descriptor (server-config.wsdd)
Defines service name
Point to web service “class” and set parameters for which methods are the web service methods
Implement “handlers”
Objects that perform Blackboard-specific processing. E.g., setContext()

30. Configuring Axis Must specify server-config.wsdd
Again, this is because the protocol doesn’t handle SecurityException
Add handlers for Blackboard-specific requirements
Authentication, Session, Context
But… no common Servlet/JSP entry point

31. server-config.wsdd Declaring the service…
<service name="CourseManager" provider="java:RPC">
<parameter name="allowedMethods" value="*"/>
<parameter name="className" value="blackboard.webservice.CourseManager"/>
</service>

32. Custom Axis Handlers “Chain of Responsibility” design pattern
Can be configured per service, or globally within the webapp
ServletFilter can be used instead of handler

33. Example – server-config.wsdd
<transport name="http">
<requestFlow>
<! >
<handler type= "java:blackboard.webservice.axis.ContextSetHandler"/>
</requestFlow>
<responseFlow>
<handler type= "java:blackboard.webservice.axis.ContextReleaseHandler"/>
</responseFlow>
</transport>

34. Example – Custom Handler
public class ContextSetHandler extends BasicHandler {
public void invoke( MessageContext msgCtx ) throws AxisFault {
try {
ContextManager ctxMgr = (ContextManager)BbServiceManager lookupService(ContextManager.class);
HttpServletRequest request =
(HttpServletRequest)msgCtx.getProperty( HTTPConstants.MC_HTTP_SERVLETREQUEST );
ctxMgr.setContext( request ); }
catch (Exception e) {
// . . .

35. Configuration – Gotcha
WSDLFactory and permissions
Create bootstrap servlet to init system property; factory locator does not recover from file system security
Reflection permissions
Axis uses reflection extensively to auto-map the Java class to WSDL and negotiate the end point

36. Using the Web Service WSDL URL: Use as input to wsdl2java
Use as input to wsdl2java

37. Checklist Class to implement web service
Class to provide handler functionality
Axis libraries
server-config.wsdd
Configuration/Bootstrap servlet
Manifest with correct permissions

38. Great. Now What?
Well, this is where truly heterogeneous programming comes in…
Sample Java Client
Sample .NET Client

39. Sample Java Client Wsdl2java WSDL URI (Ant)
Stubs +
your code
javac
Your program

40. Sample Java Client package blackboard.client;
public class SampleClient {
public static void main( String[] args ) {
try {
CourseManagerServiceLocator locator = new CourseManagerServiceLocator();
CourseManager service = locator.getCourseManager();
CourseWrapper[] list = service.getCourseList( );
for ( int i = 0; i < list.length; i++ ) {
System.out.println( list[i].getCourseId() ); }
catch( Exception e ) { }

41. Sample .NET Client WSDL URI Wsdl.exe
Stubs +
your code
Csc.exe
Your program

42. Sample .NET Client using System; namespace Blackboard.Client {
public class ServiceClient {
public static void Main( string[] args ) {
try {
CourseManagerService service = new CourseManagerService();
CourseWrapper[] list = service.getCourseList( );
System.Console.WriteLine( list.Length + " courses found." );
foreach (CourseWrapper course in list ) {
System.Console.WriteLine( course.courseId ); }
catch( Exception e ) {}

43. Conclusion Web Services are available today Some pitfalls
In different flavors, even
Some pitfalls
Promises an entirely new class of application for Blackboard

44. Thank You!