Tips & Tricks in Building Blocks Development

jetmorebrisketΛογισμικό & κατασκευή λογ/κού

15 Αυγ 2012 (πριν από 4 χρόνια και 4 μήνες)

257 εμφανίσεις

Copyright 2005 Academic Computing
-

University of South Florida

Tips & Tricks in Building
Blocks Development


Blackboard Developers Conference

July 19, 2005

Murali Nagulakonda

http://www.acomp.usf.edu/~nagulako/presentations/

Copyright 2005 Academic Computing
-

University of South Florida

1

Outline


Connecting to the Database


Storing Data in Course and User Registries


Storing Data Outside the Database


User Interfaces


<bbUI:list> Tag


<bbUI:breadcrumbBar> Tag


Context and ContextManager


Gradebook APIs


Miscellaneous




Copyright 2005 Academic Computing
-

University of South Florida

Connecting to the
Database

Copyright 2005 Academic Computing
-

University of South Florida

3

Connecting to the Database…


Use Blackboard’s API’s to connect to the DB.
(NON
-
PUBLIC APIs)


Use Blackboard’s connection pool.


Already established connections to the DB.


Doesn’t require setup/teardown of connections.


Getting a connection from the pool is faster


Set the
bb
-
manifest.xml

permissions.


import

blackboard.db.*



Copyright 2005 Academic Computing
-

University of South Florida

4

Connecting to the Database…


Setting the Bb
-
manifest permission:



<permission
type="java.lang.RuntimePermission"
name="db.connection.bb_bb60"
actions="connect,accept" />



Copyright 2005 Academic Computing
-

University of South Florida

5

Connecting to the Database…

ConnectionManager conman;

int i=0;

private Connection bbConnectDatabase() throws
ConnectionNotAvailableException, InterruptedException


{



BbDatabase bbDb = DbUtil.safeGetBbDatabase();



conman = bbDb.getConnectionManager();



while(conn == null && i<10){



try {




conn = conman.getConnection();




}




catch(ConnectionNotAvailableException cnae){




Thread.sleep(1000);




++i;


}



}



return conn;


}



Copyright 2005 Academic Computing
-

University of South Florida

6

Releasing the connection…

if(conman != null)


conman.releaseConnection(conn);

Copyright 2005 Academic Computing
-

University of South Florida

Registries

Copyright 2005 Academic Computing
-

University of South Florida

8

Registries


Course & User Registries


Excellent tables strictly for Key
-
Value pair data


Makes building blocks portable


Tables already exist


Don’t have to worry about creating them


Example of Key
“usf.spa.lastviewed"


Caveat: These are Non
-
public APIs. BB can change the
APIs & tables anytime.

Copyright 2005 Academic Computing
-

University of South Florida

9

Registries

SQL> desc course_registry;



Name





Type


-----------------------

----------------


SOS_ID_PK2


NUMBER(38)


PK1

NUMBER(38)


CRSMAIN_PK1


NUMBER(38)


CRSMAIN_SOS_ID_PK2

NUMBER(38)


DTMODIFIED


DATE


ROW_STATUS


NUMBER(1)


REGISTRY_KEY

VARCHAR2(50)


REGISTRY_VALUE

VARCHAR2(255)


DTCREATED

DATE


Copyright 2005 Academic Computing
-

University of South Florida

10

Registries

SQL> desc user_registry;



Name


Type


-----------------------

----------------


SOS_ID_PK2

NUMBER(38)


USERS_SOS_ID_PK2


NUMBER(38)


PK1

NUMBER(38)


ROW_STATUS


NUMBER(1)


REGISTRY_KEY

VARCHAR2(50)


REGISTRY_VALUE

VARCHAR2(255)


DTCREATED


DATE


USERS_PK1

NUMBER(38)


DTMODIFIED


DATE


Copyright 2005 Academic Computing
-

University of South Florida

11

Registries APIs


blackboard.persist.registry


UserRegistryEntryDbLoader


UserRegistryEntryDbPersister


CourseRegistryEntryDbLoader


CourseRegistryEntryDbPersister


blackboard.data.registry


CourseRegistryEntry


UserRegistryEntry

Copyright 2005 Academic Computing
-

University of South Florida

12

Registries



Persisting Data into a Course Registry



CourseRegistryEntryDbPersister crePersister =
CourseRegistryEntryDbPersister.Default.getInstance();



String value = lineitem_id + ":" + values;



String key = “usf.spa.lastviewed" + ":" + user_id;


try {


crePersister.deleteByKeyAndCourseId(key,cId);




// cID


Course Id of type Id


}


catch(KeyNotFoundException kfe) {}


catch(PersistenceException pe) {}


CourseRegistryEntry cre = new CourseRegistryEntry(key,value);


cre.setCourseId(cId);


try {



crePersister.persist(cre);


}


catch(PersistenceException pe) {}




Copyright 2005 Academic Computing
-

University of South Florida

13

Course Registry


Getting Data from a Course Registry


CourseRegistryEntryDbLoader creLoader =
CourseRegistryEntryDbLoader.Default.getInstance();

Registry registry = creLoader.loadRegistryByCourseId(cId);

String key = “usf.spa.lastviewed" + ":" + user_id;

String value = registry.getValue(key);



Similar for User Registry


Copyright 2005 Academic Computing
-

University of South Florida

Storing Data Outside the
Database

Copyright 2005 Academic Computing
-

University of South Florida

15

Storing Data outside the Database


Data under the /webapps
directory gets wiped out during
an update / re
-
install


Use Blackboard APIs to create
the Config Directory


Data not removed after
uninstall or update of
module


Copyright 2005 Academic Computing
-

University of South Florida

16

Storing Data in the Config Directory

Copyright 2005 Academic Computing
-

University of South Florida

17


File dir = null;


java.util.Enumeration names = request.getParameterNames();


try {


dir = blackboard.platform.plugin.PlugInUtil.getConfigDirectory("usf",





“member
-
participation");


}


catch(Exception e) {


out.println("Exception = " + e);


}


File cfg = new File(dir,“custom.properties");


FileOutputStream f = null;


if(!cfg.exists())


cfg.createNewFile();


try {


f = new FileOutputStream(cfg);


}


catch(FileNotFoundException e) {


System.out.println("cant find properties file");


}


Properties p = new Properties();



for(; names.hasMoreElements();) {


String name = (String) names.nextElement();


String value = request.getParameter(name);


p.setProperty(name,value);



}


p.store(f,“Member
-
Participation Configuration File");


f.close();


Copyright 2005 Academic Computing
-

University of South Florida

18

Storing Data outside the Database…

Copyright 2005 Academic Computing
-

University of South Florida

19

Retrieving Data from Config Directory


try {


dir = blackboard.platform.plugin.PlugInUtil.getConfigDirectory("usf","member
-
participation");


}


catch(Exception e) {


out.println("Exception = " + e);


}


File cfg = new File(dir,“custom.properties");


FileInputStream fp = null;


if(cfg.exists()) {


fp = new FileInputStream(cfg);


Properties p = new Properties();


p.load(fp);


fp.close();


sname = p.getProperty("sname");


dbname = p.getProperty("dbname");


uname = p.getProperty("uname");


pwd = p.getProperty("pwd");


}


}


Copyright 2005 Academic Computing
-

University of South Florida

<bbUI:list>

Copyright 2005 Academic Computing
-

University of South Florida

21

<bbUI:list> tag


Extremely useful in displaying lists of data


Associate a comparator to a column (
listElement
) to
enable sorting

comparator

Copyright 2005 Academic Computing
-

University of South Florida

22

<bbUI:list>

BbList llist = uLoader.loadByCourseId(cId);

GenericFieldComparator compUserName = new
GenericFieldComparator(BaseComparator.ASCENDING, "getUserName",
User.class );


Comparator

<bbUI:list collection="<%=llist %>" collectionLabel="Course Last
Access" objectId=“
user
" className=“blackboard.data.User"
resultsPerPage="
-
1">

<bbUI:listElement width = "15%" label= "Net Id" name="userName"
comparator = "<%=compUserName%>">




<%=
user
.getUserName()%>
Data to be displayed in the row

</bbUI:listElement>

</bbUI:list>

user


The object Id to refer to the data within the “llist” collection



throughout the rest of the list tag

label


Title of the column

comparator

A non required value which allows the tag to sort the data

Copyright 2005 Academic Computing
-

University of South Florida

23

<bbUI:list>

<bbUI:list collection="<%=llist %>" collectionLabel="Course Last Access"
objectId=“user" className=“blackboard.data.User"
resultsPerPage="
-
1"
>


resultsPerPage=“
-
1”: Blackboard doesn’t save state between pages. Use the “
-
1” value to tell BB not to page.



Default results per page is 20


Currently Blackboard’s list tag doesn’t save state between pages



-
1” will show all data in one page.




Copyright 2005 Academic Computing
-

University of South Florida

<bbUI:breadcrumbBar>

Copyright 2005 Academic Computing
-

University of South Florida

25

<bbUI:breadcrumbBar>


Creates the framework for the breadcrumb navigation.


breadcrumbBar attributes


handle: the database field used to uniquely identify the root nav item
for the breadcrumb bar


You can get a list of all “handles” from the database table
“Navigation_Item”


environment : Acceptable values are PORTAL, COURSE,
CTRL_PANEL, SYS_ADMIN


If you’re within a course, the page must have the “course_id” (_3320_1)
accessible to it to generate the breadcrumbBar.

Copyright 2005 Academic Computing
-

University of South Florida

26

<bbUI:breadcrumbBar>

<bbUI:breadcrumbBar handle="control_panel“>

<bbUI:breadcrumb>Student Performance Assistant</bbUI:breadcrumb>

</bbUI:breadcrumbBar>



Requires the <bbUI:docTemplate>


Requires <bbData:context>


For the context to properly generate you should have the “course_id” when coming from
the control panel and pass it on to the subsequent pages.

Copyright 2005 Academic Computing
-

University of South Florida

27

<bbUI:breadcrumbBar>

<bbUI:breadcrumbBar
handle
="
usf
-
student
-
performance
-
nav
-
1
“>

<bbUI:breadcrumb>Student Performance Student View</bbUI:breadcrumb>

</bbUI:breadcrumbBar>



handle

values


If it is a course plugin


Eg: From the Tools or Communication Area


The handle is “
vendor_id
-
plugin_handle
-
nav
-
1



Eg: usf
-
student
-
performance
-
nav
-
1


The numbers continue upwards.


Must have course_id.


No “
handle
” if it is a portal module.




Copyright 2005 Academic Computing
-

University of South Florida

28

<bbUI:breadcrumbBar> …


From the portal


No handle or way to
generate the breadcrumb
using the Public APIs.


To generate the
breadcrumb, import:



blackboard.persist.navigation


blackboard.data.navigation

Copyright 2005 Academic Computing
-

University of South Florida

29

<bbUI:breadcrumbBar




String tab_id = referer.substring(referer.indexOf("_"),referer.lastIndexOf("_1")+2);

Id tabId = bbPm.generateId (Tab.DATA_TYPE,tab_id);

//bbPm


Blackboard Persistence Manager

TabDbLoader tabLoader = TabDbLoader.Default.getInstance();

Tab t = tabLoader.loadById(tabId);

label

= t.getLabel();

TabControl tc = TabControl.createInstance(t);

if(request.isSecure()) {


strTab

= "https://" + request.getServerName() + tc.getFullUrl(request.getServerName());


}


else {


strTab

= "http://" + request.getServerName() + tc.getFullUrl(request.getServerName());


}


JSP PAGE

<bbUI:breadcrumbBar environment="PORTAL">

<bbUI:breadcrumb
href
="<%=
strTab
%>"><%=
label
%></bbUI:breadcrumb>

<bbUI:breadcrumb>Select Participation Parameters</bbUI:breadcrumb>

</bbUI:breadcrumbBar>



Referer from Header= http://redfrog.acomp.usf.edu/webapps/portal/tab
/
_109_1
/index.jsp

Copyright 2005 Academic Computing
-

University of South Florida

Context & Context
Manager

Copyright 2005 Academic Computing
-

University of South Florida

31

Context & ContextManager


Context


Combination of Session Data & Client Request


<bbData:context id=“ctx”> tag in jsp pages


Set the context before calling the API methods


Get User: ctx.getUser();


Get Course: ctx.getCourse();


Get CourseMembership: ctx.getCourseMembership();


Get UserId: ctx.getUserId();


Copyright 2005 Academic Computing
-

University of South Florida

32

ContextManager

If used within a Java class


import blackboard.platform.context


ctxMgr = (ContextManager)BbServiceManager.lookupService(
ContextManager.class );

Context ctx = ctxMgr.setContext(request);

//… work with the APIs

if( ctxMgr != null )


ctxMgr.releaseContext();


Copyright 2005 Academic Computing
-

University of South Florida

Gradebook APIs

Copyright 2005 Academic Computing
-

University of South Florida

34

Gradebook APIs

Lineitem

Score

CourseMembership

User

Copyright 2005 Academic Computing
-

University of South Florida

35

Gradebook APIs

Connection conn = getConnection(); // Use the code sample shown previously
to get a connection from the connection pool.

LineitemDbLoader lLoader = (LineitemDbLoader)
bbPm.getLoader(LineitemDbLoader.TYPE);

Lineitem li = lLoader.loadById(lId); // lId is LineitemID

BbList sList = li.getScores();

BbList.Iterator sIterator = sList.getFilteringIterator();

CourseMembershipDbLoader cmLoader =
CourseMembershipDbLoader.Default.getInstance();

Id cmId ;

CourseMembership cm ;

User user;

String username;

while(sIterator.hasNext())

{


Score score = (Score) sIterator.next();


cmId = score.getCourseMembershipId();


cm = cmLoader.loadById(cmId,conn,true); // true tells the loader to load
all the associated User Data


user = cm.getUser();


username = user.getUserName();

}









Lineitem
Score
CourseMembership
User
Lineitem
Score
CourseMembership
User
Copyright 2005 Academic Computing
-

University of South Florida

36

Miscellaneous…


All the “Non
-
Public” APIs shown here and not in the
documentation
can

change when blackboard updates its
software.


You can use Netbeans to look at the non
-
public APIs.


For building blocks APIs, load the bb
-
platform.jar.


Don’t have to re
-
install a building block everytime you
make changes to the class files.


An “Active


Inactive

Active” will get Tomcat to
reload the file.


Exceptions to this rule are for the bb
-
manifest.xml file
and the web.xml file


Copyright 2005 Academic Computing
-

University of South Florida

37

Miscellaneous


Building blocks may have multiple entry points


E.g. Portal pages, Control Panel, Tools…


Before deploying, make sure you have good logging
information which goes to the tomcat logs


Copyright 2005 Academic Computing
-

University of South Florida

38

Resources


Bbug.ca


Bb
-
opensource.org mailing list


Building Blocks APIs


behind.blackboard.com


Copyright 2005 Academic Computing
-

University of South Florida

39

Questions or Comments?


Murali
Nagulakonda

University of South Florida

4202 E. Fowler Ave., LIB 618

Tampa, FL 33620

nagulako@usf.edu