Title: Developing Sakai Services and Tools
1Developing Sakai Services and Tools
- Mark J. Norton
- Senior Technical Consultant
- The Sakai Project
2Overview
- General Information
- Creating APIs
- Implementing Service
- Writing Tools
- Framework Considerations
- Development Example
- Coming Attractions Framework 2
3Building Tools with a Framework
4The Sakai Framework
- Architecture overview
- Sakai has a simple, layered architecture.
- The Sakai framework
- Common services are part of the framework
- JSF, Spring, Context, Hibernate
5Sakai 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
6Abstract 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
7Sakai 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
8Sakai 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
9The 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
10The 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
11Design 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.
12Development 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.
13Application Service Interfaces
14Application Service Interfaces
- What is a Sakai Service?
- What is available?
- Common practices
- Definitions
Interface Design Pattern
15Sakai 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.
16Two 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.
17OSIDs 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.
18Sakai 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
19Example API vs. OSID
Org.osid.agent.Agent
Interface
OSID Adaptor Component
Implementation
Org.sakaiproject.common.service.Agent
Org.sakaiproject.common.component.agent.Agent
20The 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
21The 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
22Which 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
23Sakai 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
24Including 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).
25Implementing Components
26Service Implementations
- Further design considerations
- Writing an application service
- Using Common Services
- Injecting dependent services
- Persistence hibernate
27OKI 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.
28Application 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.
29Application 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).
30Migrating 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!
31Creating 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.
32Creating 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.
33Using Common Services
34Dependency 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
35Object 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
36Data 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.
37Generic 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.
38Example Presentation Service
- The presentation service manages three objects
Slide
Presentation Manager
Presentation
Show
39The Slide Class
- A simple POJO containing the following data
elements - URL
- Display Name
- Content
- Type (MIME type)
40The 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)
41Notes 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.
42The Presentation Class
- The Presentation class is a structured collection
of slides - Identifier
- Title and Author properties
- Slide set
- Wait slide
43The 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)
44Notes 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.
45Service 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
46Service 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
47Legacy Services
48Legacy 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
49Legacy 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.
50How 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
51Identify 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)
52Inject 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
53Inject 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
54Provide 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.
55Use 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
56Identify 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)
57Resources and the Content API
(Javadoc)
- The ContentHostingService manages uploaded files
and folders, their properties, and permissions.
58Resources 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)
59Legacy 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.
60Resources 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
61Resources 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
62JSF 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
63Developing Tools
64Tool Development
- The MVC Pattern and JSF
- Creating New Tools
- UI Design using Faces
- Service Injection
- Application Context
- Using the Style Guide
65Tools 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
66Creating 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
67The 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).
68Designing 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
69JSF 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
70Backing 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()
71Service 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.
72Application Context
73The 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.
74Tool Development Example
75Overview 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
76A 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
77The 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.
78Presentation Views
- The tool has four basic presentation states
Each of these state diagram nodes become a JSF
view.
79Main 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.
80Presentation 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.
81The 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).
82JavaServer 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.
83JSF 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().
84Faces-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.
85main.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.
86How 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
87Messages.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.
88Writing 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.
89Presentation 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.
90Presentation 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) ....
91Tool 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.
92Tool 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.
93Tool 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.
94Tool 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.
95Servlet 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.).
96Tool 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.
97Registering 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.
98Components.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.
99Component 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).
100Deployment
101Deployment and Development
- Directory Structure
- Deployment
- Eclipse and Maven
- The CVS Repository
- Bug reporting and tracking
- UI Review
- Porting Existing Tools
102Structure 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
103Module 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
104Configuration Files
- Component.xml
- Service components to be injected.
- Web.xml
- Servlet definitions
- Faces-config.xml
- JSF configuration (also injection)
- Messages.properties
- Display messages, etc.
105Deployment
- 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
106Code Deployment
Interface Code
Tomcat Shared/lib
Component Code
Tomcat webapps
Tool Code
Local Repository
107Creating 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.
108Working 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
109The 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.
110Eclipse 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.
111The 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
112UI 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.
113Bug 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.
114Debugging 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.
115Porting 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).
116Development 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.
117How 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.
118Portability
119Portability 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.
120Porting 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.
121Interoperability 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.
122Sneak Preview!
123Sakai 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.
124Sakai 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.
125The 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
126Sakai 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.
127IMS 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.
128Things You Can Do
129Call 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
130Read 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
131Participate 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
132Development 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.
133Sakai 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
134Resources
- 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/
135Questions?