Download Web Services and Blackboard

Web Services and Blackboard
Bob Alcorn
Blackboard, Inc.
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 1995. 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,
2005. 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, 2005. Blackboard, in its sole discretion,
may delay or cancel the release of any product or functionality described in this
presentation.
Overview
• Web Services Overview
– High-level, not a detailed tutorial
• Relationship to Blackboard Building
Blocks™
• Consuming Web Services
• Creating Web Services
Audience
• Familiarity with Java Servlet
programming
• Familiarity with HTTP
• Experience with Blackboard Building
Blocks
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
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
Web Services and Blackboard
Building Blocks
• Consumer
– Add “call out” capability to your extensions
• Producer
– Expose your methods via Web Services
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
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
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…
Web Services – Technical
Issues
• API Granularity
– Calls are expensive, incorporating the
overhead of
•
•
•
•
XML serialization
Network (HTTP) communication
XML de-serialization
…and back again
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
Using Web Services
Get Some
WSDL
Generate
Stubs
E.g., wsdl2java
Provided by the Web Service
Write code
Using Stubs
Package
Webapp
The code you write
Deploy to
Blackboard
The standard B2
packaging
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”/>
Configuration – Gotcha!
• client-config.wsdd must be readable by
the extension (e.g., WEB-INF)
– Set property first!
Configuration – Gotcha!
• You must declare additional
permissions
– RuntimePermission,
accessDeclaredMembers
– PropertyPermission,
javax.wsdl.factory.WSDLFactory, write
– RuntimePermission, getClassLoader
– RuntimePermission, createClassLoader
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…
Generating Stubs
• For typed invocation
– 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
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"/>
Generating Stubs – Ant Task
<axis-wsdl2java
output="src“
verbose="true“
url=“${merlot.wsdl}”>
<mapping
namespace="http://www.blackboard.com/ls/webservices/“
package="blackboard.client"/>
<mapping namespace="http://localhost/webapps/bb-webservicebb_bb60/services/CourseManager"
package="blackboard.client"/>
</axis-wsdl2java>
Example – Permissions
<permissions>
<permission . . . />
<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>
Example – Using the Stubs
String queryTerms = request.getParameter("queryTerms");
//get config file
String fileName =
getServletContext().getRealPath( "/WEB-INF/clientconfig.wsdd" );
AxisProperties.setProperty(
EngineConfigurationFactoryDefault.OPTION_CLIENT_CONFIG_FILE
, fileName );
GoogleSearchServiceLocator locator = new
GoogleSearchServiceLocator();
GoogleSearchPort googleSearch =
locator.getGoogleSearchPort();
GoogleSearchResult result =
googleSearch.doGoogleSearch( . . . );
elements = result.getResultElements();
Checklist
•
•
•
•
Axis libraries
client-config.wsdd
Stub generator/stubs
Client class with configuration to
bootstrap properties
• Manifest with correct permissions
.NET APIs and Web Services
• CLR APIs introduced in Blackboard
Academic Suite™ version 6.1.5 used to
expose basic Web Services, via
ASP.NET
• Methods correspond to
loaders/persisters in APIs
• Windows only
Using .NET API Web Services
• Example using Java
• Generate stubs
– http://server/BlackboardWebServices/
AnnouncementWebService.asmx?wsdl
• Implement authentication
– Currently only supports Blackboard
authentication
– Credentials passed via SOAP header
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();
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
Web Service Class
public class CourseManager {
public CourseWrapper[] getCourseList( String userName )
{
//… work goes here
}
}
Axis Tasks
• Implement Class
• Configure Axis deployment descriptor (serverconfig.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()
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
server-config.wsdd
Declaring the service…
<service name="CourseManager" provider="java:RPC">
<parameter name="allowedMethods" value="*"/>
<parameter name="className"
value="blackboard.webservice.CourseManager"/>
</service>
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
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>
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) {
// . . .
}
}
}
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 automap the Java class to WSDL and negotiate
the end point
Using the Web Service
• WSDL URL:
– http://server/webapps/bb-servicebb_bb60/services/ServiceName?wsdl
• Use as input to wsdl2java
Checklist
•
•
•
•
•
•
Class to implement web service
Class to provide handler functionality
Axis libraries
server-config.wsdd
Configuration/Bootstrap servlet
Manifest with correct permissions
Great. Now What?
• Well, this is where truly heterogeneous
programming comes in…
• Sample Java Client
• Sample .NET Client
Sample Java Client
WSDL URI
Wsdl2java
(Ant)
http://localhost/webapps/vid-handle-bbuid/services/YourService?wsdl
Stubs +
your code
javac
Your program
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 ) {
}
}
}
Sample .NET Client
WSDL URI
Wsdl.exe
http://yourserver/webapps/id-vid-bbuid/services/YourService?wsdl
Stubs +
your code
Csc.exe
Your program
Sample .NET Client
using System;
namespace Blackboard.Client
{
public class ServiceClient
public static void Main(
try {
CourseManagerService
CourseWrapper[] list
{
string[] args ) {
service = new CourseManagerService();
= service.getCourseList( . . . );
System.Console.WriteLine( list.Length + " courses found." );
foreach (CourseWrapper course in list ) {
System.Console.WriteLine( course.courseId );
}
}
catch( Exception e ) {}
}
}
}
Conclusion
• Web Services are available today
– In different flavors, even
• Some pitfalls
• Promises an entirely new class of
application for Blackboard
Thank You!