Walkthrough of Java APIs

1
Walkthrough of Java APIs

• Presented By Tracy Engwirda

28 September, 2005
2
Overview

• Background
• Walk through of Java APIs
• High level review of packages, patterns
• Building Block Overview

3
Audience

• Knowledge of Java programming
• People who want an overview of the entire range
  of functionality exposed
• (without resorting to reading the docs)
• Thinking of building, dont know what to look at
  first

4
Design Goals High Level

• Decouple persistence from data objects
• XML and Database
• Originally targeted for import/export
• Database abstraction
• Iterative functionality
• Start with simple objects, mapped to the legacy
  schema
• Managed extensibility
• System extensions and deployment model

5
A Little History
Import/Export
Building Blocks
Module Developer Kit
R6 Gradebook
R6 Assessment
R6 Portal
6
Building Blocks Architecture
Business Layer (JSP, Servlet, Struts)
View Layer (JSP, Servlet, Tag Library)
Data Objects
Core Services
7
Road Map

• Data objects and packages
• What data can I see?
• Persistence objects and packages
• How do I get to the data?
• Service objects and packages
• How do I log it, authenticate it, etc.?

8
Which API is that?

• blackboard. Building Block API
• blackboard.admin. Release 6 Admin API
• com.blackboard.event. Bb 5.5 Event
  API (deprecated)

9
Building Block API Packages
announcement
navigation
blackboard.data.
calendar
role
content
course
gradebook
user
announcement
navigation
blackboard.persist.
calendar
role
content
course
gradebook
user
10
Building Block API Packages
blackboard.platform.
context
filesystem
session
log
persistence
plugin
blackboard.portal.
blackboard.base.
blackboard.util.
11
Data Objects

• blackboard.data
• Object view of the schema
• Typed to wrap legacy database constructs
• Type-safe enumerations for constrained database
  columns
• User.Role.SYSTEM_ADMIN

12
Data Objects BbObject

• Base object for all data objects
• Common attributes Primary Key (Id), dates, etc.
• Smart attributes
• Properties stored in an internal map, instead of
  member variables
• Smart load, dirty flag
• Id attribute helps define lifecycle
• Id.UNSET_ID default id for new objects

13
Data Objects Content

• blackboard.data.content
• Content is the root object that can be used in
  the content areas of a course
• All other objects are simple subclasses of
  Content that over-ride specific values
• Custom content types should create and manipulate
  Content objects not CourseDocument objects.
• CourseDocument can be used to manipulate the base
  Item type

14
Data Objects Content

• ContentHandler
• Ties content to URI-based handlers
• This is really the B2 glue for custom content
• IsFolder
• Can the object contain other objects
• IsLesson
• Should the contents be displayed sequentially
• Plus many more added in Bb 6.3

15
Data Objects Content
16
Data Objects Course

• blackboard.data.course
• Course and Organization
• Organization overrides course for specific
  attributes
• Course Enrolment
• CourseMembership
• Enumerated roles
• CourseMembership.Role.INSTRUCTOR
• Course Groups and Group Enrolment

17
Data Objects Gradebook

• blackboard.data.gradebook
• LineItem
• Defines the columns in a course gradebook
• Score
• Wraps the actual outcome for a given line item

18
Data Objects Misc.

• Announcement
• Wraps announcements
• Can be system or course level
• Calendar
• Wrap entries in the calendar
• Course and System level

19
Persistence Objects

• Intended to be decoupled from data objects
• Interfaces allow replaceable persistence
  implementations
• Currently proprietary to Blackboard
• BbPersistenceManager
• Ties together different aspects of persistence
• Loader/Persister broker
• Container

20
Persistence Objects Id

• Used to encapsulate the unique identifier for
  each data object
• Primary key, and more
• Data type
• Container (database)
• GUIDs are not used, so keys can collide

21
Persistence Objects Loaders

• Base interface to get at data
• Roughly one-to-one correspondence to data objects
• All type-specific loaders are geared towards
  known predicates
• loadById()
• loadByUserIdandType()
• Performance. Ad hoc queries can kill the system
• Schema stability

22
Persistence Objects Persisters

• Perform any action that manipulates data
• Again, one-to-one correspondence with data
  objects
• Smart update
• Id object state determines insert vs. update

23
Accessing Persisters and Loaders

• Theyre interfaces, not directly instantiated by
  callers
• BbPersistenceManager is the broker
• Most have a Default object for direct access
• ContentDbLoader loader ContentDbLoader.Default.g
  etInstance()

24
Putting It Together

• Content content new Content()
• content.setTitle()
• // etc. . .
• ContentDbPersister contentPersister
• ContentDbPersister.Default.getInstance()
• contentPersister.persist( content )

25
Putting It Together v2

• Content content new Content()
• content.setTitle()
• // etc. . .
• // new reflection-based persistence methods
• content.persist()

26
Services

• Infrastructure for common utility functions
• Exposed as interfaces (mostly)
• Lookup via BbServiceManager

27
Service Lookups
LogService logService BbServiceManager.getLo
gService() LocaleManager locMgr
BbServiceManager.getLocaleManager() ContextManag
er ctxMgr (ContextManager)BbServiceManager
.lookupService( ContextManager.class )
28
Services Context

• blackboard.platform.context
• Critical entry point that all code must call
• Context wraps information about current request
  to get the correct database connection
• Interact via ContextManager.setContext() and
  ContextManager.releaseContext()

29
Services Session

• blackboard.platform.session
• State for the current browser-based client
• Stores authentication status
• Cookie-based session management
• Database persistent to share between Perl and
  Java processes
• Some assembly required
• Not all HTTP-clients (e.g., media plugins for
  browsers) honor the host browsers cookies

30
Services Filesystem

• blackboard.platform.filesystem
• FileSystemService - Broker different file system
  locations
• Course and content
• E.g., getContentDirectory()

31
Services Log

• blackboard.platform.log
• Simple write-only log implementation
• Supports configurable levels
• Written before log4j and JDK 1.4

32
Services Security

• blackboard.platform.security
• Authentication and Authorization
• AccessManagerService

33
Package Base

• Mix of utility objects
• List functionality
• BbList should use List instead though
• GenericFieldFilter
• GenericFieldComparator
• Comparator implementation that can sort based on
  arbitrary properties
• Works with String, Boolean, Dates, and Comparable

34
Package Base

• BbEnum base class for all type-safe
  enumerations
• FormattedText encapsulation of text data
  entered via standard Text boxes
• Defines enumeration for Smart, Plain, and HTML
  text
• NestedRuntimeException/NestedException pre-JDK
  1.4 facility for chaining exceptions

35
Portal

• blackboard.portal.external
• CustomData is all youll need
• getModuleData()
• getModulePersonalizationData()
• Store name/value
• Value can be string, or binary object

36
Administrative API Packages
blackboard.admin.data.
user
course
category
datasource
blackboard.admin.persist.
user
course
category
datasource
37
Administrative APIs

• blackboard.admin.
• APIs geared towards data integration
• Formerly called the Event APIs
• Repackaged to be more consistent with B2 APIs
• Compatibility layer supported
• Base classes used in Snapshot

38
Administrative APIs

• Follows IMS Data Model
• Person, Course (Group), and Membership
• Additional objects for Blackboard usage
• Category
• Data Source
• Defines logically related entities that can be
  managed independently via Snapshot

39
Beyond APIs UI Integration

• Tag Libraries
• Encapsulate re-usable UI components to capture
  the Blackboard look and feel
• Tag Library Descriptors
• Re-use within individual web applications
• .tld files

40
Beyond APIs - Deployment

• Not an API, per se
• Critical aspect of extension development
• XML manifest used to generate records in the
  database that define navigation, content brokering

41
Tying It All Together

• A Building Block may require touching several
  different APIs
• Set context
• Authorize current User
• Load content object
• Access Gradebook data
• Perform custom calculation
• Log result
• Render results (bracketed via tags)
• Release context

42
Thoughts

• There are a lot of classes to look at
• Focus on the type of Building Block you need to
  build
• Take it methodically, iteratively. Whats your
  first goal? Second goal?
• Think of combining functions
• What can I do using Content with Gradebook?

43
Questions?