Developing Sakai Services and Tools

1
Developing Sakai Services and Tools

• Mark J. Norton
• Senior Technical Consultant
• The Sakai Project

2
Overview

• General Information
• Creating APIs
• Implementing Service
• Writing Tools
• Framework Considerations
• Development Example
• Coming Attractions Framework 2

3
Building Tools with a Framework
4
The Sakai Framework

• Architecture overview
• Sakai has a simple, layered architecture.
• The Sakai framework
• Common services are part of the framework
• JSF, Spring, Context, Hibernate

5
Sakai Architecture

• Descriptions of the Sakai Architecture are being
  collected into a set of documents
• The Tool Portability Profile defines how to write
  Sakai tools and is being updated
• The architecture is intended to promote tool
  portability and data interoperability

6
Abstract Sakai Architecture
Client
The aggregator combines content from various
sources into a single user interface experience.
Aggregator
The presentation layer allows the user interface
to be described separately from the tool code.
Presentation
The tool handles events and adjusts data for
presentation back to the user/client
Sakai Framework
Tool
Services provide abstract capabilities for
application logic and common support functions.
Services
The system includes Tomcat, the webserver, file
system, databases, etc..
System
7
Sakai Design Patterns

• Separation of Tool Logic and UI
• Velocity and JSF separate UI representation.
• Service Injection
• Spring and JSF inject services as needed.
• Model View Controller
• JSF
• Object persistence via ORM
• Legacy uses XML fragments, later we use
  Hibernate.
• Coding to APIs
• Sakai APIs and OKI OSIDs.

Look for the Pattern Symbol
8
Sakai Framework Technology

• Hibernate for object persistence
• Sakai APIs that imitate OKI OSIDs
• Tools are based on APIs and servlets
• JavaServer Faces separate out the presentation
  from tool logic
• uPortal integrates tools at the UI level

9
The Sakai 1 Framework
Browser
Apache Tomcat
response and request
Jetspeed Portal
iFrame Based Portal
Velocity or JSF
rendering
Tool
Component Manager
injection
Application Services
Spring
injection
Common Services
10
The Sakai Module

• A Sakai module consists of
• A tool.
• Application services.
• Implementations of those services.

TheTool
Service Interface A
Service Interface B
Implementation of A
Implementation of B
Common Services
11
Design Methodology

• Consider the users needs first.
• Develop the user interface (prototyping).
• Next consider your application services.
• Develop their interfaces.
• Implement them as components.
• Write the tool to connect UI to services.

12
Development Considerations

• User interface design is critical, but out of
  scope for this workshop. Have a close look at
  the Sakai Style Guide and consider user centric
  design approaches.
• Lets take a close look at what goes into an
  application service interface and implementation.
• Then well explore tool development.

13
Application Service Interfaces
14
Application Service Interfaces

• What is a Sakai Service?
• What is available?
• Common practices
• Definitions

Interface Design Pattern
15
Sakai Services - Definition

• A Sakai Service is a collection of classes
  defined by an interface that provides an
  integrated set of functionality.
• Roughly split between application and common
  services.
• Tools call on services for the functions they
  provide.
• Services may depend on other services.
• Services are portable, modular, and reusable.

16
Two Kinds of Interfaces

• Sakai APIs
• Older legacy services and newer common services.
• Sakai APIs are designed to make it easy to create
  powerful Sakai tools
• OKI OSIDs
• Focused on access to data.
• OKI OSIDs are designed to maximize tool
  portability to environments other than Sakai.

17
OSIDs and APIs

• Sakai has interface requirements above and beyond
  the OKI OSIDs
• There is no way to cleanly extend the OKI OSIDs
• Therefore, Sakai is creating a set of APIs that
  correspond as closely as possible to the OSIDs,
  but extend them in various ways.
• The OSIDs are covers over the Sakai services.

18
Sakai APIs

• Make tool development easier
• Promote portability between Sakai environments
• Hide some data management details
• Simplify Error handling
• Provide re-usable system and application services
  to tool developers

19
Example API vs. OSID
Org.osid.agent.Agent
Interface
OSID Adaptor Component
Implementation
Org.sakaiproject.common.service.Agent
Org.sakaiproject.common.component.agent.Agent
20
The OKI Agent OSID
package org.osid.agent public interface Agent
extends java.io.Serializable public String
getDisplayName() throws
osid.shared.SharedException public
osid.shared.Id getId() throws
osid.shared.SharedException public
osid.shared.Type getType() throws
osid.shared.SharedException public
PropertiesIterator getProperties()
throws osid.shared.SharedException Properties
getPropertiesByType(Type propertiesType)
throws osid.shared.SharedException public
TypeIterator getPropertiesTypes()
throws osid.shared.SharedException
Serializable
Access only
Exceptions
OKI Interators
21
The Sakai Agent API
package org.sakaiproject.service.common.agent pu
blic interface Agent public String
getDisplayName() public void
setDisplayName(String displayName) public Long
getId() public String getReferenceName()
public void setReferenceName(String
referenceName) public Type getType() public
void setType(Type type) public String
getUuid() public void setUuid(String uuid)
public Integer getVersion() public Node
getNode() public void setNode(Node node)
public String getAlias() public void
setAlias(String alias)
Same name
POJO style
Java GUIDs
Sakai features
22
Which Interface Should I Use?

• Use the Sakai APIs
• To develop Sakai tools
• To access Sakai service features
• Use the OKI OSIDs
• For maximum tool portability
• When data modification isnt relevant

23
Sakai API Guidelines

• Include convenience methods and objects built on
  OKI methods (e.g. equals())
• Include Java-oriented methods which directly
  relate to underlying OKI language-neutral
  equivalents (e.g. Calendar)
• Include Java-oriented methods which tie more
  directly to the Sakai framework, increasing
  performance at the expense of portability to
  non-Sakai environments.
• Extend beyond the OSIDs to allow explicit
  exposure of out of band agreements
• Extend beyond the OSIDs to allow for
  easy/simple/natural support of use-cases not
  directly supported by current OSID specifications
• Methods should be evaluated carefully for what
  exceptions are thrown

• Java-based exception classes and subclasses are
  used for the exceptions thrown
• Consider using exceptions which are subclasses of
  RuntimeException A method is not required to
  declare in its throws clause any subclasses of
  RuntimeException that might be thrown during the
  execution of the method but not caught.
• Implementations of the APIs may be java beans
  therefore the APIs use set/get in a
  bean-compatible way
• Methods may use/return Java-native
  objects/interfaces, e.g. Calendar, io.stream
• The term 'properties' is used for consistency
  with OKI, but the Java interface used for this is
  a Map
• Sakai iterators extend java.util.Iterator

24
Including Services in a Module

• The service APIs associated with a Sakai module
  should be contained in a sub-directory of the
  module (called service).
• Service APIs are deployed to the shared lib
  directory of Tomcat via Maven.
• Services are registered with the Sakai Component
  Manager to make them available to the tool (and
  other services).

25
Implementing Components
26
Service Implementations

• Further design considerations
• Writing an application service
• Using Common Services
• Injecting dependent services
• Persistence hibernate

27
OKI Application OSIDs

• There are a few OKI application level OSIDs
• Repository, Grading, Course Management, and
  Assessment. All of these are being developed.
• If your application is closely based on these
  service use the existing implementations if
  possible.
• If you need to create a new implementation, use
  the OKI OSID 2.0 interface definitions and have a
  close look at other implementations.

28
Application Service Design

• Follow the best practices exhibited in other
  services, for example use a Manager class to
  create and access service objects.
• Give careful thought to the classes included in
  the service.
• Non-OSID services dont need an OSID style cover
  interface.

29
Application Service Characteristics

• Calls common services via injection.
• Deals with objects reflected in a user interface.
• Defines a process or workflow.
• Might be tied to an app or tool.
• Designed to be generally usable in many tools
  (repository service, for example).

30
Migrating a Legacy Service

• Migration of legacy services will be handled by
  the core Sakai development team, in general.
• Since legacy tools are closely tied to these
  services, service migration must be coordinated
  with tool migration.
• Talk to Mark or Chuck before doing anything!

31
Creating a Brand New Service

• Define the Interface based on Sakai service best
  practices.
• Use the TPP for guidelines.
• Define data modules and definitions.
• Use Hibernate for object persistence.
• Write a test harness application (or unit tests).
• Submit the new service for evaluation and release.

32
Creating an Application Service

• Check to see if anyone has already created
  something similar to this service.
• Define the interface based on Sakai best
  practices.
• Use the TPP for guidelines.
• Define data modules and definitions.
• Use Hibernate for object persistence.
• Write a test harness application (or unit tests).
• Submit the new service for evaluation and release.

33
Using Common Services
34
Dependency Injection

• Bean style access and setters
• Inserted at runtime by the Spring container
• Dependencies are defined in XML configuration
  files, as appropriate.
• This is one of the standard design patterns
  described further in the TPP document.

Injection Design Pattern
35
Object Persistence

• Hibernate provides ORM support.
• Objects are persisted to a database.
• Hibernate handles atomic Java data types, POJOs,
  collections, and complex objects.
• HQL allows selective object retrieval which can
  be optimized by DBAs.
• Support for transactions, locking, clustering,
  and multi-stage caching.

ORM Design Pattern
36
Data Models

• Standards
• Use existing industry standards where available.
• Data Elements
• Design and document your data elements and
  organization.
• Access Model
• Use object persistence. Avoid DB dependencies.
• Interchange consider data migration needs.

37
Generic vs. Custom Repositories

• Sakai will provide a generic repository
• It will provide basic file management, access
  control, and metadata support.
• You may have special needs which require a custom
  repository.
• Capabilities can be layered on the Sakai
  Repository or you can build one from scratch.

38
Example Presentation Service

• The presentation service manages three objects

Slide
Presentation Manager
Presentation
Show
39
The Slide Class

• A simple POJO containing the following data
  elements
• URL
• Display Name
• Content
• Type (MIME type)

40
The Slide Interface
package org.sakaiproject.service.presentation pu
blic interface Slide extends java.io.Serializable
public String getUrl() public void
setUrl(String url) public Serializable
getContent() public void setContent(Serializable
content) public String getDisplayName() publi
c void setDisplayName(String name) public
String getType() public void setType(String
type)
41
Notes on the Slide Interface

• A POJO interface allows easy access via Spring,
  Hibernate, and JavaServer Faces.
• URLs are represented by strings here, but they
  could be Java URLs classes as well.
• Content type is managed by using a Type object as
  a MIME type, similar to the OKI Filing OSID.

42
The Presentation Class

• The Presentation class is a structured collection
  of slides
• Identifier
• Title and Author properties
• Slide set
• Wait slide

43
The Presentation API
public interface Presentation extends
java.io.Serializable public static final
String PRESENTATION_TITLE "org.sakaiproject.tool
s.presentation.title" public Id
getId() public void setId (Id id) public
String getTitle () public void setTitle (String
title) public String getAuthor () public void
setAuthor (String author) public List
getSlides() public Slide getSlide (int
offset) public void addSlide(Slide
slide) public int getSlideCount() public void
deleteSlide (int position) public void
insertSlide(int position, Slide slide) public
Slide getWaitSlide() public void
setWaitSlide(Slide waitSlide)
44
Notes on the Presentation API

• Convenience methods provided for easy access to
  title and author properties.
• Access to a List object instead of an iterator.
• Most of the heavy lifting is done by the
  Presentation Manager class.

45
Service Example Agent
package osid.agent public interface Agent
extends java.io.Serializable public String
getDisplayName() throws
osid.shared.SharedException public
osid.shared.Id getId() throws
osid.shared.SharedException public
osid.shared.Type getType() throws
osid.shared.SharedException PropertiesIterator
getProperties() throws
osid.shared.SharedException Properties
getPropertiesByType(Type propertiesType)
throws osid.shared.SharedException
TypeIterator getPropertiesTypes()
throws osid.shared.SharedException
package org.sakaiproject.service.common.agent imp
ort org.sakaiproject.service.common.shared.Resourc
e public interface Agent extends Resource
46
Service Example Resource
package org.sakaiproject.service.common.shared im
port org.sakaiproject.exception.PermissionExceptio
n import org.sakaiproject.exception.VersionExcept
ion import org.sakaiproject.service.common.id.Id
public interface Resource extends Comparable
String getDescription() String
getDisplayName() Id getId()
Type getType() PropertiesIterator
getProperties() Properties
getPropertiesByType(Type propertiesType)
TypeIterator getPropertyTypes() void
setDescription(String description) void
setDisplayName(String displayName) void
setType(Type type) String
getReference() String getUrl()
boolean allowDelete() boolean
allowUpdate() Properties
addPropertiesType(Type propertiesType)
void removePropertiesType(Type propertiesType)
void delete() throws PermissionException
Version getVersion() boolean
isCurrentVersion() boolean
isCurrentVersion(Version version) void
update() throws VersionException,
PermissionException void
updateIgnoreVersion() throws PermissionException

47
Legacy Services
48
Legacy Services

• Jon Andersen of U. Michigan will talk for 15 20
  minutes on Sakai Legacy Services including
• Active user
• Active worksite
• Authorization
• Resources and content API

49
Legacy Services

• Legacy services were created primarily for the
  tools in the 1.0.0 release (Announcements, Chat,
  Resources, etc)
• Legacy services manage all persistent data such
  as current user, current site, security, and
  tool-specific information.
• Legacy services will evolve as JSF tools are
  developered and OKI OSID services mature, and a
  migration path will be provided.

50
How to use Legacy Services

• Identify the needed legacy service
• Inject the legacy service into your own tool bean
  or service
• Use the legacy service in your tool bean logic or
  service logic
• Provide access methods in the tool bean for the
  data or actions that the JSF page requires

51
Identify Needed Services
package org.sakaiproject.service.framework.portal
public interface PortalService
String getCurrentSiteId() String
getCurrentSitePageId() String
getCurrentToolId()
Q How do I find out about the current user,
site, page or tool?
package org.sakaiproject.service.legacy.user pub
lic interface UserDirectoryService
User getCurrentUser()
A Use one of the legacy services (until Sakai
2.0)
package org.sakaiproject.service.legacy.site pub
lic interface SiteService boolean
allowUpdateSite(String siteId)
52
Inject needed services (1)
(faces-config.xml)
ltfaces-configgt ltmanaged-bean-namegtMyToollt/mana
ged-bean-namegt ltmanaged-bean-classgtorg.sakaipr
oject.tool.mytool.MyToollt/managed-bean-classgt
ltmanaged-bean-scopegtrequestlt/managed-bean-scopegt
ltmanaged-propertygt ltdescriptiongtServic
e Dependency UserDirectoryServicelt/descriptiongt
ltproperty-namegtuserDirectoryServicelt/proper
ty-namegt ltvaluegtComponents"org.sakaipro
ject.service.legacy.user.UserDirectoryService"lt/
valuegt lt/managed-propertygt
ltmanaged-propertygt ltdescriptiongtService
Dependency SiteServicelt/descriptiongt
ltproperty-namegtsiteServicelt/property-namegt
ltvaluegtComponents"org.sakaiproject.service.leg
acy.site.SiteService"lt/valuegt
lt/managed-propertygt ltmanaged-propertygt
ltdescriptiongtService Dependency
PortalServicelt/descriptiongt
ltproperty-namegtportalServicelt/property-namegt
ltvaluegtComponents"org.sakaiproject.service.f
ramework.portal.PortalService"lt/valuegt
lt/managed-propertygt lt/managed-beangt lt/faces-co
nfiggt
Legacy services are indexed by the class names of
the service interfaces
53
Inject needed services (2)
(MyTool.java)
public class MyTool implements ToolBean
private UserDirectoryService
m_userDirectoryService private SiteService
m_siteService private PortalService
m_portalService public void
setUserDirectoryService(UserDirectoryService
service) this.m_userDirectoryService
service public void
setSiteService(SiteService service)
this.m_siteService service public
void setPortalService(PortalService service)
this.m_portalService service
Setters enable JSF to inject the services
selected by faces-config.xml
54
Provide access methods
(MyTool.java)
public class MyTool implements ToolBean
public User getCurrentUser() return
m_userDirectoryService.getCurrentUser()
public String getCurrentSiteId()
return m_portalService.getCurrentSiteId()
public boolean getCanCurrentUserModifySite(
) return m_siteService.allowUpdateSite(m
_portalService.getCurrentSiteId())
Access methods enable the JSF page to interact
with the legacy services.
55
Use in JSF
(main.jsp)
... lt_at_ taglib uri"http//sakaiproject.org/jsf/sa
kai" prefix"sakai" gt ... ltfviewgt ltsakaiview_co
ntainer title"msgs.sample_title"gt lthformgt
... ltsakaiview_contentgt ...
ltsakaigroup_box title"msgs.sample_one_groupbox
"gt ltsakaipanel_editgt ...
lthoutputText value"Site ID (1.0.0)" /gt
lthoutputText value"MyTool.currentSiteId" /gt
lthoutputText value"Current user" /gt
lthoutputText value"MyTool.currentUser.di
splayName" /gt lthoutputText value"Can
current user modify the structure of this site?"
/gt lthoutputText value"MyTool.canCurren
tUserModifySite" /gt lt/sakaipanel_editgt
lt/sakaigroup_boxgt ... lt/sakaiview_content
gt lt/hformgt lt/sakaiview_containergt lt/fviewgt
JSF value references can access JavaBean-style
getters in service-managed objects
56
Identify Needed Services
http//cvs.sakaiproject.org/release/1.0.0/javadoc/
index.html
Lots of services
only a few that tools will likely access
org.sakaiproject.service.framework.cluster
org.sakaiproject.service.framework.component
org.sakaiproject.service.framework.config
org.sakaiproject.service.framework.courier
org.sakaiproject.service.framework.current  
org.sakaiproject.service.framework.email
org.sakaiproject.service.framework.log
org.sakaiproject.service.framework.memory
org.sakaiproject.service.framework.portal
org.sakaiproject.service.framework.session
org.sakaiproject.service.framework.sql  
org.sakaiproject.service.legacy.alias
org.sakaiproject.service.legacy.announcement
org.sakaiproject.service.legacy.archive
org.sakaiproject.service.legacy.assignment
org.sakaiproject.service.legacy.calendar
org.sakaiproject.service.legacy.chat
org.sakaiproject.service.legacy.content
org.sakaiproject.service.legacy.digest
org.sakaiproject.service.legacy.discussion
org.sakaiproject.service.legacy.dissertation
org.sakaiproject.service.legacy.email
org.sakaiproject.service.legacy.event
org.sakaiproject.service.legacy.id
org.sakaiproject.service.legacy.news
org.sakaiproject.service.legacy.notification
org.sakaiproject.service.legacy.preference
org.sakaiproject.service.legacy.presence
org.sakaiproject.service.legacy.realm
org.sakaiproject.service.legacy.resource
org.sakaiproject.service.legacy.security
org.sakaiproject.service.legacy.site
org.sakaiproject.service.legacy.time
org.sakaiproject.service.legacy.user
portal Portal info site Manages Sakai
sites user Current user, manage users content
Uploaded files (resource tool) courier
Automatic refreshing when content changes email
Send email log Logging sql SQL access to
Sakai DB preference User preferences security
Check user permissions (security)
57
Resources and the Content API
(Javadoc)

• The ContentHostingService manages uploaded files
  and folders, their properties, and permissions.

58
Resources and the Content API
(Javadoc)
package org.sakaiproject.service.legacy.content
public interface ContentHostingService extends
ResourceService String getSiteCollection(Stri
ng siteId) ContentCollection getCollection(Strin
g collectionId) ContentCollectionEdit
addCollection(String collectionId) ContentResour
ce addResource(String id, String type, byte
content, ResourceProperties properties, int
priority) ContentResourceEdit
editResource(String resourceId) void
commitResource(ContentResourceEdit
editedResource) void cancelResource(ContentResou
rceEdit editedResource) boolean
allowUpdateResource(String resourceId) boolean
allowUpdateCollection(String collectionId) allow
Rename(String oldId, String newId) allowAddColle
ction(String collectionId) allowAddAttachmentRe
source() ResourceProperties getProperties(String
collectionOrResourceId)
59
Legacy Service Patterns

• Objects - Service manages a collection of objects
  (ie, ContentCollection, AnnouncementMessage,
  ChatMessage, Calender, CalenderItem). Service
  manages entire lifecycle of the objects.
• Security - allowXXX() methods check that the
  current user has proper permissions for XXX
  operation. Also, some methods do inline
  permissions checking and throw PermissionException
  if the operation is not allowed.
• References - Many managed objects implement the
  Resource interface, and can be referenced through
  an internal ID, a internal string URI, or an
  externally accessible URL.
• Properties - Managed objects that implement
  Resource have standard properties (created by,
  last modified, etc) and arbitrary tool-specific
  properties.

60
Resources and the Content API
(Javadoc)
package org.sakaiproject.service.legacy.content
public interface ContentHostingService extends
ResourceService String getSiteCollection(Stri
ng siteId) ContentCollection getCollection(Strin
g collectionId) ContentCollectionEdit
addCollection(String collectionId) ContentResour
ce addResource(String id, String type,
byte content, ResourceProperties properties,
int priority) ContentResourceEdit
editResource(String resourceId) void
commitResource(ContentResourceEdit
editedResource) void cancelResource(ContentResou
rceEdit editedResource) boolean
allowUpdateResource(String resourceId) boolean
allowUpdateCollection(String collectionId) allow
Rename(String oldId, String newId) allowAddColle
ction(String collectionId) allowAddAttachmentRe
source() ResourceProperties getProperties(String
collectionOrResourceId)
Access objects
Edit objects
Check permissions
Access properties
61
Resources and the Content API
Example code snippet from the Presentation Service
package org.sakaiproject.service.legacy.content
public class PresentationManagerImpl implements
PresentationManager public List
getPresentations() String home
contentHostingService.getSiteCollection(PortalServ
ice.getCurrentSiteId()) String
collectionId home Presentations/
try ContentCollection
collection contentHostingService.getCollection(c
ollectionId) int size
newMembers.size() for (int i
0 ilt size i) Resource
resource (Resource) newMembers.get(i)
String nextId resource.getId()
boolean isCollection
resource.getProperties().getBooleanProperty(Resour
ceProperties.PROP_IS_COLLECTION)
if (isCollection)
loadPresentation(nextId)
catch (PermissionException e)
(Inform the user that they are not allowed to do
that) catch (IdUnusedException
e) catch (TypeException e)
catch (EmptyException e)
return this.presentations
62
JSF toolConfig Variable
(Javadoc)

• The implicit JSF variable toolConfig provides
  convenient access to some common textual
  information that might be displayed in a tool.
  More properties will be available in the Sakai
  1.5 release.

1.0.0 release toolConfig.toolId toolConfig.ti
tle toolConfig.containingPage.title toolConf
ig.containingPage.containingSite.title toolConf
ig.containingPage.containingSite.description to
olConfig.containingPage.containingSite.type too
lConfig.containingPage.containingSite.skin tool
Config.containingPage.containingSite.joinable
Added in 1.5.0 release (or in CVS
now) toolConfig.pageId toolConfig.siteId t
oolConfig.containingPage.containingSite.createdBy
toolConfig.containingPage.containingSite.modifi
edBy toolConfig.containingPage.containingSite.c
reatedTime toolConfig.containingPage.containing
Site.modifiedTime toolConfig.containingPage.con
tainingSite.shortDescription toolConfig.contain
ingPage.containingSite.published toolConfig.con
tainingPage.containingSite.pubView
63
Developing Tools
64
Tool Development

• The MVC Pattern and JSF
• Creating New Tools
• UI Design using Faces
• Service Injection
• Application Context
• Using the Style Guide

65
Tools Glue Things Together
Controller Design Pattern
JavaServer Faces
GUI Element
Faces-config.xml
View Design Pattern
ltxmlgt ltfacesgt lt/xmlgt
Sakai Tool Class
Action Method
Model Design Pattern
Application Service Class
App Logic
66
Creating a New Tool

• Describe the UI using JSF pages.
• Create an Application Service.
• Implement the Application Services.
• Create a Tool Class which uses the application
  service via injection.
• Create Maven project files to compile and deploy.
• Register the tool with the Component Manager

67
The Tool Class

• Written as a JavaBean so that JavaServer Faces
  can access it. It is the model part of the MVC
  pattern.
• Application and common services are injected as
  needed.
• Handles initializations and data defaults.
• Implements JSF response methods (events).

68
Designing a UI

• Wire frames and layouts should be used to get a
  feel for views needed and flow in the
  application.
• Standard Sakai elements are defined to ensure
  consistent look and feel
• Standard Sakai layouts are provided for standard
  UI containers (boxes, toolbars, forms, etc.).

Separate UI Design Pattern
69
JSF is Used to Describe the UI
ltsakaiview_container title"msgs.sample_title"
gt
ltsakaitool_bargt ltsakaitool_bar_item/gt
lt/sakaitool_bargt
ltsakaiinstruction_message value"msgs.sample_on
e_instructions" /gt
ltsakaigroup_box title"msgs.sample_one_groupbo
x"gt
lthinputText value"MyTool.userName" /gt
ltsakaidate_input value"MyTool.date" /gt
ltsakaibutton_bargt ltsakaibutton_bar_item actio
n"MyTool.processActionDoIt value"msgs.sampl
e_one_cmd_go" /gt lt/sakaibutton_bargt
70
Backing Beans Handle Action
lthinputText value"MyTool.userName" /gt
MyTool.userName()
ltsakaidate_input value"MyTool.date" /gt
MyTool.date()
ltsakaibutton_bargt ltsakaibutton_bar_item actio
n"MyTool.processActionDoIt value"msgs.sampl
e_one_cmd_go" /gt lt/sakaibutton_bargt
MyTool.processActionDoIt()
71
Service Injection

• Sakai uses a service injection pattern to resolve
  dependencies at runtime.
• This is a kind of Inversion of Control (IoP).
• The Spring Framework handles initialization of
  manager objects and injects dependent services.
• This is all done in XML configuration files.
• Allows version dependencies.

72
Application Context
73
The Sakai Style Guide

• Includes illustrations of Sakai GUI elements and
  widgets.
• JSF tags are described with options noted.
• Use considerations and best practice.
• Accessibility and uPortal guidelines.
• A draft version of the Sakai Style Guide will be
  released during or following the SEPP conference.
  See Rob Lowdens presentation.

74
Tool Development Example
75
Overview of Tool Development

• Sample Methodology
• Design the UI (mockups, wireframe)
• Write the JSF descriptions
• Write the application interface and service
• Write and configure the tool
• Porting tools

76
A Development Methodology
Wireframes
Id Panels and Modes
Make Services
Make Backing Beans
Develop UI with JSF
Click Thru Mockup
Developed by Ben Brophy and the MIT Gradebook
team.
Tool Integration
77
The Presentation Tool

• Upload a set of slides and make them available as
  a presentation that can be shown to one or more
  viewers with simple controls.
• Currently implemented using a Presentation
  service based on direct file access.
• Being integrated with Sakai Legacy services
  (Content API, etc).
• Use the presentation CVS root.

78
Presentation Views

• The tool has four basic presentation states

Each of these state diagram nodes become a JSF
view.
79
Main Page
These are presentations available to be shown
Buttons provide the transition to other faces.
Presentations are managed by an application
service
Uses the Sakai Style Guide Elements
Shows are run time objects that are deleted once
complete.
80
Presentation Controls
Only a single controller of a presentation is
allowed. Three controls are provided at this
time go to next, go to previous, and end the
presentation. The current slide is shown for
reference.
81
The Viewer Page
Any number of people may view the presentation.
The interactive option is to exit the viewer.
Current slide is synchronized via a file. Viewer
refreshes every 20 seconds (settable).
82
JavaServer Faces

• Tool pages are described by JavaServer Faces tags
  using a JSP file as a container.
• Each page is a JSF view.
• Sakai supports the standard JSF tags.
• Eventually, Sakai will have a full set of tags
  which represent the Sakai GUI elements, to be
  documented in the Sakai Style Guide.
• This set is partially implemented and under
  development.

83
JSF Navigation

• JSF Views are described in JSP files.
• Navigation from one view to the next is handled
  by returning the name of the next view. Return
  null to stay with current view.
• The transition from main.jsp to show.jsp is
  handled by returning show out of
  processActionShow().

84
Faces-config.xml
ltfaces-configgt ltapplicationgt
ltmessage-bundlegtorg.sakaiproject.tool.mytool.bundl
e.Messageslt/message-bundlegt
ltlocale-configgtltdefault-localegtenlt/default-localegt
lt/locale-configgt lt/applicationgt
ltmanaged-beangt ltdescriptiongtPresentation Tool
Beanlt/descriptiongt ltmanaged-bean-namegtPresentatio
nToollt/managed-bean-namegt ltmanaged-bean-classgtorg
.sakaiproject.tool.mytool.PresentationToollt/manage
d-bean-classgt ltmanaged-bean-scopegttoollt/managed-b
ean-scopegt ltmanaged-propertygt ltdescriptiongtSer
vice Dependency Presentation Servicelt/description
gt ltproperty-namegtprMgrlt/property-namegt ltvaluegt
Components"org.sakaiproject.service.pr
esentation.PresentationManager" lt/valuegt lt/ma
naged-propertygt lt/managed-beangt lt/faces-configgt
This is how the Presentation Service is injected
into the Presentation Tool. This is a reference
to the Sakai Component Manager.
85
main.jsp
ltsakaigroup_box title"msgs.pt_showing_groupbox
"gt lthformgt ltsakaitool_bargt ltsakaitool_b
ar_item action"PresentationTool.processActio
nJoin" value"msgs.pt_join_button"
/gt lt/sakaitool_bargt ltsakaiview_contentgt lth
messages showSummary"true" showDetail"true"
/gt lt-- the list of presentations
--gt ltsakaiflat_list value"PresentationTool.
prMgr.shows" var"show"gt lthcolumngt lt--
Check box column. --gt ltffacet
name"header"gt lthoutputText
value""/gt lt/ffacetgt lthselectBooleanChec
kbox value"show.presentation.selected"/gt lt/
hcolumngt lthcolumngt lt-- The title column.
--gt ltffacet name"header"gt lthoutputTex
t value"msgs.pt_col_head_title"
/gt lt/ffacetgt lthoutputText
value"show.presentation.title"/gt lt/hcolumn
gt lt/sakaiflat_listgt ltsakaibutton_bargt lts
akaitool_bar_item action"PresentationTool.
processActionJoin" value"msgs.pt_join_butt
on" /gt lt/sakaibutton_bargt lt/sakaiview_conte
ntgt lt/hformgt lt/sakaigroup_boxgt
This is the showing box on main page. The list
of presentations is similar, but more complex.
86
How JSF Looks Rendered
ltsakaigroup_box title"msgs.pt_showing_groupbox
"gt
ltsakaitool_bargt ltsakaitool_bar_item/gt
lt/sakaitool_bargt
ltsakaiflat_list value"PresentationTool.prMgr.s
hows" var"show"gt
lthcolumngt ltffacet name"header"gt
lthoutputText value"msgs.pt_col_head_title"
/gt lt/ffacetgt lthoutputText
value"show.presentation.title"/gt lt/hcolumngt
lthcolumngtltffacet name"header"gt
lthoutputText value""/gt lt/ffacetgt lthselectBoole
anCheckbox value"show.presentation.selecte
d"/gt lt/hcolumngt
ltsakaibutton_bargt ltsakaitool_bar_item action"
PresentationTool.processActionJoin" value"
msgs.pt_join_button" /gt lt/sakaibutton_bargt
87
Messages.Properties
pt_new_buttonNew pt_delete_buttonDelete pt_show_
buttonShow pt_col_head_titleTitle pt_col_head_a
uthorAuthor pt_title_mainPresentation
Tool pt_presentation_groupboxPresentations
These are the messages used on the Main view of
the presentation tool. Property names are
conventions to make it easier to keep things
straight,
The messages.properties file defines text
resources that can be inserted into JSF
renderings, accessed by backing beans, etc.
Internationalization support is provided
by having alternative versions of this file with
country code extensions.
88
Writing the Application Service

• Design the Application Service
• Think about reuse at this stage.
• Good object design will benefit all.
• Implement it as a POJO managed bean.
• Access is provided via a Manager class.
• Other services can be defined as dependencies and
  injected by the Spring container.

89
Presentation Service - Interface
package org.sakaiproject.service.presentation pu
blic interface PresentationManager
IdManager getIdManager() void setIdManager
(IdManager im) public Show getShow (Id
id) public List getShows() public Show
getCurrent () public void setCurrent (Show
show) public Show createShow (Presentation
presentation) public void deleteShow (Id
id) public Presentation getPresentation (Id
id) public List getPresentations()
public Presentation createPresentation(List
slides, String title, String author) public
void deletePresentation (Id presentationId)
public Slide createSlide(String url, String name,
String type) public void load() public
void save() public void updateShowFile(Show
show) public Slide readShowFile(Show show)

Allows the IdManager to be injected.
This List is displayed as available shows.
This List is displayed as available presentations.
Initialization is done automatically.
90
Presentation Service Manager
public class PrManager implements
org.sakaiproject.service.presentation.Presentation
Manager protected IdManager idManager
null private List presentations new
Vector() private List shows new
Vector() public List getPresentations()
return this.presentations public
Presentation createPresentation(List slides,
String title, String author) Id id
null try id this.idManager.createId()
catch (Throwable t) return null
Presentation pres (Presentation) new
PrPresentation(id, slides, title, author)
this.presentations.add (pres) return
pres public void deletePresentation(Id
id) Presentation pres
this.getPresentation (id)
this.presentations.remove(pres) ....
91
Tool Implementation

• Tool classes typically have a set of properties
  (data elements).
• Each property has get and set methods, so that
  Spring can manage it as a bean.
• The tool is registered as a bean.
• The tool has JSF event handler methods.

92
Tool Data Elements
public class PresentationTool / Service
Dependency Presentation Service. / protected
PresentationManager prMgr null .
The Presentation Manager is the main access point
in the Presentation Tool. Most of the faces code
access information via this object.
93
Tool Access Methods
public class PresentationTool public
PresentationManager getPrMgr () return
this.prMgr public void setPrMgr
(PresentationManager mgr) this.prMgr
mgr .
Since the tool is a managed bean, both set and
get methods must be provided that correspond to
the data element.
94
Tool Event Handlers
public class PresentationTool public String
processActionShow() Show currentShow
null List prs this.prMgr.getPresentations()
for (int i0 iltprs.size() i) // Scan
for selected presentation. Presentation pres
(Presentation) prs.get(i) if
(pres.getSelected() true) currentShow
prMgr.createShow (pres) this.shows.add
(currentShow) this.prMgr.setCurrent
(currentShow) pres.setSelected(false)
if (currentShow null) return main
// Nothing selected. this.slide
currentShow.getCurrent() // Set the current
slide. return "show" // Transfer to the
show page (the controller).
Returning the name of the next view is how
transfer to the view happens.
95
Servlet Definition

• Each Sakai tool is defined as a Tomcat servlet.
  In Sakai, servlets can access code in other
  servlets, which not the case for most web
  applications.
• This is handled by the Sakai Dispatcher and the
  FacesServlet along with the Sakai Component
  Manager.
• This also forces code into specific spots for
  delivery (shared/lib, repository, etc.).

96
Tool Web.xml
ltweb-appgt ltdisplay-namegtsakai-present-toollt/di
splay-namegt ltdescriptiongtSakai Presentation
Toollt/descriptiongt ltcontext-paramgt
ltparam-namegtjavax.faces.STATE_SAVING_METHODlt/param
-namegt ltparam-valuegtserverlt/param-valuegt
lt/context-paramgt ltservletgt
ltservlet-namegtFaces Servletlt/servlet-namegt
ltservlet-classgtjavax.faces.webapp.FacesServletlt/s
ervlet-classgt ltload-on-startupgt 2
lt/load-on-startupgt lt/servletgt
ltservlet-mappinggt ltservlet-namegtFaces
Servletlt/servlet-namegt lturl-patterngt.jsflt
/url-patterngt lt/servlet-mappinggt
ltwelcome-file-listgt ltwelcome-filegtindex.ht
mllt/welcome-filegt lt/welcome-file-listgt lt/web-
appgt
This is an edited version of the tool web.xml
file showing how the Faces servlet is mapped.
97
Registering a Service

• Registering a service requires that the interface
  being shared/lib and the component be included in
  the local repository.
• The component.xml file is used to define how
  dependent services are injected into this
  service.
• To make the service visible to other services or
  tools, it must be registered with the Sakai
  Component Manager.
• This is done in the web.xml file of the component.

98
Components.xml
ltbean id"org.sakaiproject.service.presentation.Pr
esentationManager" class"org.sakaiproject.compo
nent.presentation.PrManager" init-method"init"
singleton"true"gt ltproperty
name"idManager"gtltref bean"org.osid.id.IdManager"
/gtlt/propertygt ltproperty name"hosting"gt ltre
f bean"org.sakaiproject.service.legacy.content.Co
ntentHostingService"/gt lt/propertygt lt/beangt
Defines an identifier for the Presentation
service and what class it is associated with.
IdManager is included as a dependency.
99
Component web.xml
ltweb-appgt ltdisplay-namegtsakai-present-componen
tlt/display-namegt ltdescriptiongtSakai
Presentation Service Implementationlt/descriptiongt
ltservletgt ltservlet-namegtcomponent
slt/servlet-namegt ltservlet-classgtorg.sakaip
roject.component.ComponentsServletlt/servlet-classgt
ltinit-paramgt
ltparam-namegtcomponents-filelt/param-namegt
ltparam-valuegtcomponents.xmllt/param-valuegt
lt/init-paramgt
ltload-on-startupgt1lt/load-on-startupgt
lt/servletgt ltservlet-mappinggt
ltservlet-namegtcomponentslt/servlet-namegt
lturl-patterngt/components/lt/url-patterngt
lt/servlet-mappinggt ltwelcome-file-listgtltwelcom
e-filegtindex.htmllt/welcome-filegtlt/welcome-file-lis
tgt lt/web-appgt
This is where the component is registered with
the Sakai Component Manager. A URL mapping is
provided for debugging (list components).
100
Deployment
101
Deployment and Development

• Directory Structure
• Deployment
• Eclipse and Maven
• The CVS Repository
• Bug reporting and tracking
• UI Review
• Porting Existing Tools

102
Structure of a Sakai Module

• A Sakai module is a collection of code chunks
  that will be deployed to various places in the
  Tomcat environment.
• Each module has an application service API,
  application service implementation, and a tool
  implementation.

/module name
/service
/component
/tool
103
Module Directory Structure
/
Each of the three directories under the module
root has pretty much the same structure. Not all
files are present in all directories, though.
/service
/component
/tool
maven.xml
project.xml
/src
/bundle
properties
/java
code
/webapp
web.xml
index.html
components.xml
/WEB-INF
faces-config.xml
/tool-name
JSF pages
104
Configuration Files

• Component.xml
• Service components to be injected.
• Web.xml
• Servlet definitions
• Faces-config.xml
• JSF configuration (also injection)
• Messages.properties
• Display messages, etc.

105
Deployment

• Deployment is the process of moving code and
  resources into the Tomcat (etc) environment which
  enables the tool to be included in a particular
  Sakai environment.
• Software is broken down into three parts forming
  a module
• APIs (interface)
• Service Components
• Tool

106
Code Deployment
Interface Code
Tomcat Shared/lib
Component Code
Tomcat webapps
Tool Code
Local Repository
107
Creating a Module from Scratch

• Create a module directory structure similar to
  other Sakai modules.
• Use other configuration files as templates.
• Design and write the application service
  interface.
• Implement the application service
• Design UI and describe in JSF pages.
• Write the tool to handle JSF events . Etc.

108
Working with Maven

• Maven is a powerful software configuration and
  management tool.
• Project files describe software dependencies
  which are resolved against project goals.
• Each module has its own project.xml file.
• The deploy module has a special project.
• http//maven.apache.org/start/download.html

109
The Maven Project File

• The maven documentation describes how to set up
  dependencies. Use other modules as a project
  file template.
• If you stray from the Sakai templates, you are on
  your own! Be careful of version agreement.
• Maven will generate error messages if it fails
  and indicate Build Failed if not successful.

110
Eclipse Support

• Eclipse provides several plug-ins which can
  simplify the development process
• base XML editing
• JSF layout
• Servlet definitions and editing
• Maven project editing
• Eclipse is strongly recommended as the best IDE
  for developing Sakai tools.
• myEclipse is even better since it provides
  additional tools and better XML support.

111
The Sakai CVS Repository

• Sakai has created a public CVS repository
• cvs.sakaiproject.org
• Top level branches for
• Sakai Framework
• Sakai Assessment and Assignment Manager
• Public read only access
• Project leaders will have commit access

112
UI and QA Review

• Sakai is setting up a UI Review team to review
  submitted UI designs, prototypes, and completed
  code.
• Similarly, a Sakai QA team is being set up to
  test code and ensure that it meet Sakai quality
  standards.
• Contact Mark Norton for now, more information
  later.

113
Bug Reporting

• Sakai has settled on using JIRA as its bug
  reporting and tracking system.
• Report problems at bugs.sakaiproject.org
• If you are developing tools, you may want to
  register as a developer. Send mail to
  knoop_at_umich.edu.
• Registering means fixing bugs reported against
  your code.

114
Debugging Techniques

• Use JUnit testing.
• Attaching to Tomcat
• You can set Tomcat up to listen on a debug port
  and then connect to it from Eclipse.
• Problems with injection
• Injection problems will generate entries in
  tomcat console and log files.
• Make sure of configuration files and constructors.

115
Porting Tools to Sakai

• Use existing page snapshots to design JSF
• Separate out presentation from application logic.
• Pull application services out into stand alone
  services.
• Re-code to use existing services.
• Use similar tool implementations to help with
  configuration files (etc).

116
Development Projects

• Project coordination via SEPP work groups.
• Write up a proposal containing who, what, and by
  when and send to me.
• Projects can be managed and developed by a single
  institution, or set up as a collaborative effort.

117
How Code is Released

• Currently, Indiana is controlling the 1.5
  release.
• Later, a release manager will be in charge of
  what goes into a particular release.
• Submissions should be vetted by the Sakai QA and
  UI review teams.

118
Portability
119
Portability Considerations

• Sakai is an integration framework which allows
  tools to be combined with services using a set of
  guiding principles (TPP)
• Sakai tools are intended to be portable to other
  Sakai sites.
• Non-Sakai tools can be brought into the Sakai
  environment with limited integration.

120
Porting Applications

• Tools can be developed to be portable with other
  frameworks
• Use OSIDs and Web Services
• Or tools can be ported and integrated into Sakai
• Follow the guidelines for porting a tool.
• Use Sakai APIs and TPP.
• Test final functionality against the original.

121
Interoperability Considerations

• Use industry interoperability standards where
  available
• IMS specifications, SCORM profile
• IEEE and ISO standards
• W3C, IETF, GRID, etc.
• Services should include the concept of import and
  export using these interchange standards.

122
Sneak Preview!
123
Sakai 1.5

• SAMigo
• Grade book (maybe)
• OSP
• Presentation Tool
• Framework improvements
• More common services
• Gap satisfaction

More information on the future of Sakai releases
will be reported during the SEPP Conference
starting tomorrow.
124
Sakai 2.0 - Spring 2005

• Significant replacement of legacy tools
• TPP Compliant, using OKI and Sakai APIs
• New and improved tools based on Sakai-wide
  requirements process
• Each partner institution will focus on a set of
  tools to develop
• SEPP partners will be involved in the new tool
  development based on ability and commitment.

125
The Sakai 2 Framework
Browser
Apache Tomcat
response and request
uPortal
Other Portals
JavaServer Faces
rendering
Tool
Component Manager
injection
Application Services
Spring
injection
Common Services
ORM
Hibernate
126
Sakai and OKI

• OKI has produced a series of APIs to support
  learning management system portability
• Enterprise Integration
• Tool Portability
• The OKI APIs allow for flexible out-of-band
  agreements
• The Sakai APIs are designed to be closely aligned
  with the OSIDs.
• Sakai will continue to work closely with OKI and
  make recommendations for changes to the OSIDs.

127
IMS Tool Portability SIG

• Sakai has approached IMS to develop a tool
  portability specification.
• A charter proposal has been written and approved
  by the IMS Technical Board.
• This spec will allows tools to be ported between
  environments by identifying certain core
  services AuthN, AuthZ, User/Group, and
  Repository.
• If your organization is a member of IMS, please
  consider participating in this effort.

128
Things You Can Do
129
Call to Action

• Participate in the discussion groups
• Develop in-house Sakai expertise
• Install and review Sakai 1.0 (etc)
• Develop or port tools to Sakai
• Contribute requirements
• Share lessons learned
• Be an active voice in how SEPP is run

130
Read SEPP Communications

• Update Message
• A weekly electronic newsletter
• Latest news
• References to papers and documentation
• Reports from discussion groups
• White Papers
• Reports on Events
• SEPP Conference

131
Participate in SEPP Discussion Groups

• Requirements UC Berkeley
• Migration Columbia
• Cross Language Support U. Washington
• User Interface Dartmouth
• Content Authoring U. Wisconsin
• Libraries - Columbia
• Developers Mark Norton

132
Development Discussion Groups

• The Sakai Devel group is now the default place
  to ask questions, report results, etc.
• This is a public group open to all.
• The SEPP group will evolve into SEPP development
  coordination, development support, and other
  issues.

133
Sakai Tool Development Skills

• Java Beans (dependency insertion)
• Understanding of Servlets
• Interface design and implementation
• OKI OSIDs and Sakai APIs
• Maven deployment techniques
• JavaServer Faces and Sakai GUI elements
• Hibernate is useful if developing new APIs

134
Resources

• Mark J. Norton
• markjnorton_at_earthlink.net
• 781-275-4070
• http//sakaiproject.org/
• http//collab.sakaiproject.org/
• sakai-user worksite
• sakai-devel worksite
• http//cvs.sakaiproject.org/

135
Questions?