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. • Let’s take a close look at what goes into an application service interface and implementation. • Then we’ll 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; public 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 isn’t relevant

23. 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 Sakai API Guidelines

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 don’t 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. 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. Dependency Injection Injection Design Pattern

35. 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. Object Persistence ORM Design Pattern

36. 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. Data Models

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; public 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(); public 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.tools.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; import org.sakaiproject.service.common.shared.Resource; public interface Agent extends Resource { }

46. Service Example: Resource package org.sakaiproject.service.common.shared; import org.sakaiproject.exception.PermissionException; import org.sakaiproject.exception.VersionException; 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