© Blackboard, Inc. All rights reserved. Java APIs in Depth: Blackboard Content System Daniel Cane Vice President Research and Development Blackboard Inc

© Blackboard, Inc. All rights reserved.

Java APIs in Depth:Blackboard Content System

Daniel CaneVice President Research and DevelopmentBlackboard Inc.

July 19th 10:15am

2

What Are Building Blocks?

» Blackboard Building Blocks are applications that developers build to extend the Blackboard platform and to integrate Blackboard with external applications, content, or services. They can include portal modules, content, specific tools, assessment engines, integration with library systems, campus bookstores, door access or print management systems just to name a few. The possibilities are endless.

3

Blackboard Content System APIs

» The Blackboard Content System uses the same Building Blocks infrastructure to enable developers to build new applications on top of the application, as well as take advantage of the underlying utility of the application itself.

4

Blackboard Content System APIs

» The APIs allow for a wide variety of access to everything from the creation and management of files and folders to their metadata, properties, and permissions. The APIs also enable programmatic access to many of the tools within the Blackboard Content System, such as the Learning Objects catalog, Portfolios, and Workflows.

5

‘Couple of Assumptions

» This presentation assumes a high-level understanding of Learning System Building Blocks infrastructures such as» Top Level Package Structure

» Blackboard.data, Blackboard.persist, Blackboard.base, etc

» B2 LS Data Model» Objects such as announcement, course, user

» B2 LS Persistence Services» Such as CourseDbLoader, CourseDbPersister, etc

6

Assumptions Contd.

» Familiarity with Bb Taglibrary» Understanding of the B2 packaging, manifest,

etc» Ability to laugh at stupid and often pointless

puns, jokes, jibes, etc that the presenter on occasion will make.

7

Other Resources

» Blackboard Learning System Javadoc» Blackboard Content System Javadoc» Blackboard Building Blocks Developers Guide» Blackboard Building Blocks: Introduction to

the Building Blocks APIs and Runtime» Blackboard Web Site» Bb Open-Source Listserv» Each other!

8

Where to start….

» I tend to first think of the “use-cases” for my application and then build user scenarios off them. Because of my background (I’m actually an Economist not a Computer Scientist) I tend to think of UI and workflow before I plan architecture, objects, and code.

» When the Content System is installed, the APIs are available to use from the entire Academic Suite, NOT just those installed which use CS specific UI hooks.

9

What you can expect in the next 30 mins

» Things I can help you with:» Who?» Where?» How?

» Things you have to figure out on your own:» What?» Why?

10

11

Who can you build for?

» You can build things for students (tools, communication, portal modules, portal tools, etc)

» You can build things for instructors (control panel tools)

» You can build things for the administrator (admin control panel, headless)

» You can build things for no-one, just because they are “really cool” and you’ve always wanted to do that…

12

13

CS Integration Points (a.k.a. UI Hooks)

» Content System Tools The link is added to the Tools box in the folder view of the Content Collection menu, and the Tools menu available from the shortcut view of the Content Collection menu.

» Content System Action Bar The link is added to the drop-down menu at the end of the Action Bar on folder listing pages in the Content Collection. Action Bar Building Blocks act on the files and folders currently selected in the folder listing.

14


» Modify Content FileThe link is added to the menu of options that appears when a user clicks Modify on a file in the Content Collection.

» Modify Content FolderThe link is added to the menu of options that appears when a user clicks Modify on a folder in the Content Collection.

15


» Manage Portfolio The link is added to the menu of options that appears when a user clicks Manage on a Portfolio on the My Portfolios page.

» My Portfolios The link is added to the My Portfolios box in the folder view of the Content Collection menu, and the Portfolios menu available from the shortcut view of the Content Collection menu.

16


» My Personal Favorite » Can you see it?

17

18

The How!

» Packages & sub-Packages» Data Objects» IDs» Persistence & Managers » Context» Permissions and Principals» Convenience and Utilities» Packaging and Distribution » … and TONS AND TONS of examples!

19

CS Data Object Packages

» The data object definitions reside in the various sub-packages of blackboard.cms.*

» The sub-packages are grouped into various functional areas like FileSystem or Portfolio.

20

CS Data Object sub-packages

bookmark Contains objects associated with Bookmarks in the system.

filesystem Contains objects used by the filesystem subsystem. This is one of the primary sub-packages within the Blackboard Content System, and contains the objects which control files and directories as well as the “CSContent” object which is part of the Blackboard Content System permissions framework.

21

CS Data Object sub-packages

lrngobj Contains objects for interacting with the Learning Object Catalog.

metadata Contains classes for manipulating metadata templates.

portfolio Contains classes for interacting with the Portfolio system.

workflow Contains classes for interacting with the Workflow system.

22

Data Object Descriptions

Entity DescriptionCSEntry This is the base class for objects (file and

folders) in the filesystem. It contains the access control entries, location, size, and metadata for objects.

See package blackboard.cms.filesystemCSFile This class represents files on the filesystem.

It contains the method for setting and getting the actual data within a file, as well as, the type of file.

See package blackboard.cms.filesystem

23

Javadoc for CSEntry

24


CSDirectory This class represents a directory in the filesystem. Methods are available for managing quotas for each directory. These quotas are the total space allotted by the owner for all files and sub-directories contained in the directory.


25

Javadoc for CSDirectory

26


CSCustomDirectory This class encapsulates “Special” directories in the filesystem. More specifically, the directory contents of a CSCustomDirectory cannot be changed, as they are managed explicitly by Blackboard Content System. For instance, the /users, /courses directories are type CSCustomDirectory


27


CSContext This key object controls the context used for determining permissions to entries, as well as, controls management of transactions. A context is the top level state manager for a series of Blackboard Content System calls. For every set of actions grouped together into one transaction, a new context is created and used. A context instance contains transactional state for that request (for example, commit or rollback). All permission checking is done through calls on the context object. See package blackboard.cms.filesystem

28

Javadoc for CSContext

29

Javadoc for CSContext Contd

30


CSAccessControlEntry The CSAccessControlEntry class provides a representation of an Access Control Entry within the Blackboard application. An object exposing the individual permissions of a file/directory for a specific user or list of users. Methods exist to both read and set the permissions.See package blackboard.cms.filesystem

31


LOItem The LOItem class provides a representation of a Learning Object Item within the Blackboard application. Learning Object Items usually refer to a physical file or folder within the Blackboard Content System, with additional metadata and status information related as metadata.See package blackboard.cms.lrnobj

LOCategory The LOCategory class provides a representation of a Learning Object category within the Blackboard application.See package blackboard.cms.lrnobj

32


Portfolio The Portfolio class provides a representation of a Portfolio within the Blackboard application. See package blackboard.cms.portfolio

Workflow The Workflow class provides a representation of a Workflow within the Blackboard application. A Workflow must have a type associated with it.See package blackboard.cms.workflow

33

Javadoc for Portfolio

34

Using Blackboard Content System Data Objects

» The following code demonstrates how to create a Portfolio object.

» Portfolio portTest = new Portfolio();» Creation of a data object in this way results in an

object with default values for all of the object’s attributes. To create a more useful Portfolio, it is necessary to create one that contains more than default values. To do this, create a default Portfolio object and call all of the appropriate “set” methods provided by the object.

35

Data object IDs

» Blackboard Content System objects use the same ID framework as Blackboard Learning System objects. » Objects have a getId() method on them» Object can be generally loaded and deleted

byId()

36

Persistence and Managers

» The Blackboard Content System uses a simplified approach for loading, deleting, and saving objects. Each of the core data objects for Portfolio, Metadata, Learning Objects, Bookmarks, and Workflows has an associated Manager.

37

Persistence and Managers

» For example, the Portfolio has a PortfolioManager class which has methods to deleteById(), loadById(), loadAccessibleByCourseId(), loadByOwner(), save(), and more. The methods within the managers are static, so they can be accessed directly.

38

Example of using IDs, Loaders, and Persisters

» For example, to load a Portfolio, make a change to it, and then save it:» Portfolio portLoaded = PortfolioManager.loadById(portId);

» portLoaded.setTitle(“Updated Title”);» PortfolioManager.save(portLoaded);

39

Using Blackboard Content System File System Objects

» Blackboard Content System filesystem objects work in a slightly different way then the other Blackboard API objects. For filesystem access, a Content System Context must first be established. This context is used to group transactions, as well as handle permission checking.

40

Creating a Content System Context

» A context is the top level state manager for a series of Blackboard Content System calls.

» For every set of actions grouped together into one transaction, a new context is created and used.

» A context instance contains a transactional state for that request (for example, commit or rollback).

41

Creating a Content System Context contd.

» All permission checking is done through calls on the Context object.

» Without a Context, whenever an exception is thrown, the state of the transactions involved would be unknown. » It would not be possible to know which transaction(s)

needed to be committed or rolled back. » The context object is used to keep track of that state and

allow or block commit attempts. Thus, the context object can be used to find out if the current transaction can be committed or not.

42

Creating a Content System Context contd.

» It is extremely important when using the context object to ensure that you properly use a try{},catch{},finally{} block to commit() or rollback() each transaction. Not doing so properly may cause deadlocks, performance degradation and unexpected behavior.

» It is recommended to always use CSContext in the following way:

43

Recommended way of using Context

» CSContext ctxCS=null;» try » {» ctxCS = CSContext.getContext();» // your code here» } » catch (Exception e) » {» ctxCS.rollback();» ctxCS=null;» } » finally » {

if (ctxCS!=null) {ctxCS.commit();

}» }

44

More on Content System Context

» The CSContext.getContext() call also has the ability to load context “as a specific user.”

» This gives the programmer the ability to determine if that user has sufficient privileges to operate on the designated CSEntry.

45

The Superuser (aka the Uberman)

» For some operations, the standard user context may be inadequate to perform the desired operation. In that case, there is a CSContext.isSuperUser() method that can be used. » Setting this to “true” and then performing the

operation is useful under certain conditions.

46

Using the Content System Context for Filesystem stuff..

» Once a CSContext is established. It is used to create new CSFiles and CSDirectories (sub classes of CSEntries).

» It is also used to load existing files and directories using the findEntry() method. The CSContext is further used to check if permissions for the current loaded context canRead(), canWrite(), canManage(), and canDelete() a specific CSEntry.

47

Using the Content System Context for Filesystem stuff.. Contd…

» The CSContext object is used to load, save, create, and manage the CSEntries in the file system.

48

Example of using Context and Entries

» Goal: Write a program that will load a specific Content System Directory and print out the contents (filenames) of that directory.

» Assumptions» The user running the program has read access

to the folder and it’s contents.

49

Example of using Context and Entries// Loads the CSDirectory object /users/dcaneCSDirectory csDirMyUserDir = ctxCS.findEntry("/users/dcane");// Gets the contents of the directory as a ListList listDirectoryContents =

csDirMyUserDir.getDirectoryContents();// Iterate through the list and print out information on the

contentsIterator iterDirectoryContents =

listDirectoryContents.iterator();while (iterDirectoryContents.hasNext()){ // the List of a directory contains CSEntry items (which can

be other dirs or files) CSEntry csEntryItem = (CSEntry) iterDirectoryContents.next(); out.println(“Hello there, I have found: “

+csEntryItem.getFullPath());}

50

“Special” Loaders for Course Dirs, User Dirs, etc…

» The CSContext also does some special loading for course directories, user directories, and eReserve directories. These loaders will return CSDirectory objects when you pass in the corresponding user or course.

51

Example of Special Loading

» For example, to load a course directory in the Blackboard Content System when the Blackboard Learning System blackboard.data.course object is present, run the following:» CSDirectory courseDir =

ctxCS.getCourseDirectory(theCourse);

52

Understanding Permissions and Principals

» The access control system for files and folders in the Blackboard Content System uses the concept of principals tied to permissions.

» A “principal” is an entity with the base class of CSPrincipal.

» This interface defines the concept of a principal, encompassing any entity to which file system access permissions may be granted.

53

Understanding Permissions and Principals contd.

» Every principal must be uniquely identified by a principal ID.

» All Blackboard Content System user and group objects extend this object.

» These objects are found in the blackboard.cms.filesystem.security package.

54


» Subclasses of this include: » CourseGroupPrincipal, CoursePrincipal,

CourseRolePrincipal, PortalRolePrincipal, PortfolioPrincipal, SystemRolePrincipal, UserPrincipal.

» These encapsulate the primary ways people are associated with permissions.

55


» A look at one in more detail helps explain this concept.

» If the goal was to give all Students in the “math10” course the access control of “Read”» The developer would first use the above information

to retrieve a CSEntry with the desired file» …and then determine the CourseRolePrincipalID

used to represent the class of users associated in a course with the specific role.

56

Understanding Permissions and Principals contd.// Load the file

CSEntry csFileToChange = ctxCS.findEntry(“/user/dcane/foo.txt”);

// determine the principal ID

String strCourseRolePrincipal = CourseRolePrincipal.cacluatePrincipalID(courseMath101, courseRoleofStudent);

57

Understanding Permissions and Principals contd.// get the Access Control Entry for that principal ID (even if it

does not exist)

CSAccessControlEntry csACE = csFileToChange.getAccessControlEntry(strCourseRolePrincipal);

// then update the permission for “read”

csACE.updatePermission(true, false, false, false);

58

Request Utility Classes for Specific UI Hooks» Content System Action Bar Building Blocks

» You will want to get a list of the files/dirs selected on the previous page.

» import blackboard.cms.servlet.CSActionRequest;» CSActionRequest actionReq = new CSActionRequest( request, response, application );

» List selectedFiles = actionReq.getSelectedPaths();

59

Request Utility Classes for Specific UI Hooks» Modify Content File/Folder Building Block

» import blackboard.cms.servlet.CSModifyEntryRequest;» CSModifyEntryRequest modifyEntryReq = new CSModifyEntryRequest( request );

» Manage Portfolio Building Block » import blackboard.cms.servlet.CSManagePortfolioRequest;» CSManagePortfolioRequest portfolioReq =

new CSManagePortfolioRequest( request );» Portfolio portfolio = portfolioReq.getPortfolio();

60

CS Changes for Packaging and Manifest File

» bb-manifest.xml» <csversion

» Element to define dependency on a specific Blackboard Content System version. The value has the same format as in the <bbversion> element. Not required.

» ifMissing>» Attribute of <csversion> element that determines

whether the package can be installed without the Content System present. Possible values are “fail” and “warn”. Not Required. Default value: warn.

61

Example of csversion in bb-manifest.xml <plugin> <name value= "Sample Plugin"/> <handle value= "plgnhndl"/> <description value= "This plugin is a sample."/> <version value= "1.0.0.1"/> <requires> <bbversion value="6.3.0"/> <csversion value="2.3.0" ifMissing=”warn”> </requires>…

62

Example of UI Hooks in CS in bb-manifest.xml

<links>

<link> <type value="cs_action"/> <name value="CS Action"/> <url value="actionbar.jsp"/> <description value="Sample CS Action Bar Plug-in"/> <icons></icons> </link> <link> <type value="cs_tool"/> <name value="CS Tool"/> <url value="tool.jsp"/> <description value="Sample CS Tool Plug-in"/> <icons></icons> </link> </links>

63

Permissions Needed in bb-manifest.xml

» <permission type="java.lang.RuntimePermission" name="db.connection.*" /> <permission type="attribute" name="user.authinfo" actions="get,set" /> <permission type="attribute" name="user.personalinfo" actions="get,set" /><permission type="persist" name="user" actions="create,modify,delete" /> <permission type="persist" name="userrole" actions="create,modify,delete" /><permission type="persist" name="course" actions="create,modify,delete" />

64Package

Documents

© Blackboard, Inc. All rights reserved. Java APIs in Depth: Blackboard Content System Daniel Cane Vice President Research and Development Blackboard Inc