Difference between revisions of "Home Library 1.0 API"

Revision as of 10:32, 14 May 2012

The Home Library manage and persist the users homes.

Architecture

The Home Library is define through an API interface (HomeLibrary project).

Currently there are two API implementation:

• HomeLibraryFS: an HomeLibrary implementation based on FileSystem and DataBase instance.
• HomeLibraryJCR: an HomeLibrary implementation based on JCR 2.0 (Java Content Repository JSR 283).

The Home Library dynamically load the implementation specified on properties file.

Home Library models

The user's homes are organized in scopes.

The users and the homes for a specific scope are managed by the HomeManager.

Each user home (Home) have a workspace area (WorkspaceArea) and a data area (DataArea).

The workspace area is the place where the user object are saved.

The data area is the place where the application, like the portlets can save user relative data.

Figure 1. Home Library Reference Architecture

Workspace Area model

Each element contained in a workspace area is a WorkspaceItem.

The workspace items are the effective user objects.

The figure 2 illustrate the WorkspaceItem model.

Figure 2. Workspace Item model

Data Area model

The figure 4 illustrate the Data Area model.

Figure 4. Data Area model

The data area is managed by the DataArea class. Each application have an application data area (ApplicationDataArea). The application data are can be obtained passing the application class to the DataArea instance.

In each application data area you can create an ApplicationData like:

• ApplicationList<E>, an List<E> interface implementation.
• ApplicationMap<K,V>, an Map<K,V> interface implementation.

Those data structure are automatically persisted when one or more element are added or removed.

Make attention: if not primitive objects are saved into the data structure when a modification is made on that object is necessary to call the dataUpdated() method to persist the new object version.

Event system

The Home Library offers an event system at WorkspaceArea level.

Access logging

The Home Library log events through the AccessLogging ASL extension.

The following events are logged:

ITEM_CREATED

When a folder item is created.

ITEM_REMOVED

When a folder item is removed.

ITEM_IMPORTED

When a folder item is imported (Make attention: the import event don't exclude the relative creation events.).

ITEM_SENT

When one item is sent to one or more users.

All log messages have this form: <PARAMETER> = <VALUE> | <PARAMETER> = <VALUE> ...

The ITEM_CREATED, ITEM_REMOVED, ITEM_IMPORTED and ITEM_SENT message type have those parameters:

ID

the item id.

NAME

the item name.

TYPE

the basket item type.

The ITEM_SENT have also the ADDRESSEES parameter, the list of item addressees (<USERNAME>,<SCOPE>;<USERNAME>,<SCOPE>;...).

Test Suite

The Home Library is provided with a test suite collecting console test and JUnit tests. More information about the test suite can be found on the Home Library (Test suite).

Setup the Home Library

Installation

To use the HomeLibrary you first need the HomeLibrary downloadable from:

• [1] last night build
• [2] gcube distribution site

Add the org.gcube.portlets.user.homelibrary.jar file to your gcore installation ($GLOBUS_PATH/lib folder).

Configuration

At the moment there are two Home Library API implementations and so two HomeManagerFacotory: FSHomeManagerFactory and JCRHomeManagerFactory. It's possible set one of them by property home-manager-factory-implementation presents in homelibrary.properties file below org.gcube.portlets.user.homellibrary.home package.

Home Library FS

The Home Library FS needs a persistence folder where to persist users workspace and data.

The persistence folder can be specified setting on homelibrary-ext.properties (below org.gcube.portlets.user.homelibrary.fs package) file the persistence-folder folder option.

Otherwise the user can specify a base-directory where the Home Library will create the persistence folder.

There are different ways to specify the base-directory:

1. set the HOME_LIBRARY_PERSISTENCE_DIR environment variable
2. set the system property catalina.base (generically set by Tomcat), then the "catalina.base/webapps/usersArea" is used a base directory
3. if none of preceding properties are specified the system tmp directory is used as base directory. Make attention, sometime the tmp folder is deleted at system reboot, use it only for test.

Inside the base directory a home_library_persistence directory is created and used as persistence folder.

Home Library JCR

The Home Library JCR needs a runtime resource to retrieve the useful infos to access to a jackrabbit repository present in the infrastructure.

Using the Home Library

How to retrieve the user Home from a servlet

To retrieve the user Home you can use the getHome static method from the HomeLibrary class. This method required only the current ASLSession.

Home home = HomeLibrary.getUserHome(session);

If you need only the WorkspaceArea you can use the getWorkspaceArea static method:

WorkspaceArea wa = HomeLibrary.getUserWorkspaceArea(session);

If you need only the DataArea you can use the getDataArea static method:

DataArea da = HomeLibrary.getUserDataArea(session);

Retrieve the user Home step by step

Firs of all is necessary to retrieve an instance of HomeManagerFactory, this can be done using the static methods from HomeLibrary class.

This example create an HomeLibrary instance that use a tmp directory (home_library_persistence) into the tmp system dir to save the library state. This directory is never deleted by the library. To reset the library state you can delete it.

HomeManagerFactory factory = HomeLibrary.getHomeManagerFactory();

Obtained the factory you can retrieve the HomeManager for a specified scope:

HomeManager manager = factory.getHomeManager(scope);

Where scope can be a GCUBEScope object or a GCUBEScope expression (for test you can use any expression).

Then we retrieve the User home:

User user = manager.createUser(portalLogin);
Home home = manager.getHome(user);

Where portalLogin is the user username used to login into the portal (for test you can use any username).

At this point we can get the WorkspaceArea with his root:

WorkspaceArea wa = home.getWorkspaceArea();
Workspace root = wa.getRoot();

or the DataArea:

DataArea da = home.getDataArea(session);

Examples

There are some example of HomeLibrary use.

WorkspaceArea examples

Show the WorkspaceArea content

The utility class WorkspaceTreeVisitor offer two method for workspace area visit:

• visitSimple which show only workspace area item name's
• visitVerbose which show rich information about each item

There is an example (root is the user root workspace):

WorkspaceTreeVisitor wtv = new WorkspaceTreeVisitor();
wtv.visitSimple(root);
wtv.visitVerbose(root);

There is a simple output:

/[root]
	/{My Default Basket}
	/{My first basket}
		/MyUrl

There is the verbose output;

/WORKSPACE/
ID: 4f45a2c6-7053-471b-bf1c-82d64dd87c50
NAME: root
DESCRIPTION: User root
CREATION TIME: 29-09-2009 08:57:42
OWNER: login: user.test, id: d34cbb17-ef7e-4677-a8a0-b7402f07bd05, scope: /test/testscope
 
	/BASKET/
	ID: 9d2bef0c-f06b-4936-86ec-3a7f6c428027
	NAME: My Default Basket
	DESCRIPTION: This is your default basket. It is created automatically by the System and is nor deletable or movable.
	CREATION TIME: 29-09-2009 08:57:42
	OWNER: login: user.test, id: d34cbb17-ef7e-4677-a8a0-b7402f07bd05, scope: /test/testscope
 
	/BASKET/
	ID: 0027bb87-ed6d-40eb-9349-dc00befc2176
	NAME: My first basket
	DESCRIPTION: This is my first basket created with the HomeLibrary
	CREATION TIME: 29-09-2009 08:57:42
	OWNER: login: user.test, id: d34cbb17-ef7e-4677-a8a0-b7402f07bd05, scope: /test/testscope
 
		/ITEM/
		[ExternalUrl]
		ID: ffb1c03b-529b-440d-9f3d-e0a20d787852
		NAME: MyUrl
		DESCRIPTION: This is my url
		CREATION TIME: 29-09-2009 08:57:42
		OWNER: login: user.test, id: d34cbb17-ef7e-4677-a8a0-b7402f07bd05, scope: /test/testscope
		Url https://technical.wiki.d4science.research-infrastructures.eu/documentation/index.php/Home_Library
		Length 97

Generate an unique name for a folder item

When is necessary to generate an unique item name for a given folder, there is the WorkspaceAreaUtil utility class.

String nameCandidate = "My first basket";
 
String name = WorkspaceAreaUtil.getUniqueName(nameCandidate, root);

If an item with My first basket already exists, a new name My first basket(n) since it not conflict with others one.

Retrieve the default basket

Each WorkspaceArea have a default basket, a special basket that can't be deleted or renamed.

Basket defaultBasket = workspaceArea.getDefaultBasket();

Create an ExternalUrl into a basket

After had retrieved the user workspace root:

Basket basket = root.createBasket("My first basket", "This is my first basket created with the HomeLibrary");
 
basket.createExternalUrlItem("MyUrl", "This is my url", "https://technical.wiki.d4science.research-infrastructures.eu/documentation/index.php/Home_Library");
 
WorkspaceTreeVisitor wtv = new WorkspaceTreeVisitor();
 
wtv.visitVerbose(root);

Create an ExternalFile into a basket

After had retrieved the user workspace root:

Basket basket = root.createBasket("My first basket", "This is my first basket created with the HomeLibrary");
 
File myFile = new File("build.xml");
InputStream fileData = new FileInputStream(myFile);
 
basket.createExternalFileItem("My External File", "This is an external file", "text/xml", fileData);
 
WorkspaceTreeVisitor wtv = new WorkspaceTreeVisitor();
 
wtv.visitVerbose(root);

Create a GPOD-Link into the default basket

After had retrieved the user workspace root:

Basket defaultBasket = workspaceArea.getDefaultBasket();
 
GeospatialCoordinate gc = new GeospatialCoordinate(new Date(), new Date(), "test-minLongitude", "test-minLatitude", "test-maxLongitude", "test-maxLatitude", "test-geospatialZone");
TaskInfo taskInfo = new TaskInfo("test-task-id", "test-token", "test-task-name", "test-username", gc);
 
List<String> hdfUrls = new LinkedList<String>();
hdfUrls.add("ftp://test.org/test.hdf");
 
List<String> imgUrls = new LinkedList<String>();
imgUrls.add("ftp://test.org/test.png");
 
String thumbnailUrl = "ftp://test.org/thumb.png";
String metadataUrl = "ftp://test.org/metadata.xml";
 
defaultBasket.createGPODLink("My First GpodLink", "A very usefull gpod link", "test-username", "test-psw", hdfUrls, imgUrls, thumbnailUrl, metadataUrl, taskInfo);
 
WorkspaceTreeVisitor wtv = new WorkspaceTreeVisitor();
 
wtv.visitVerbose(root);

DataArea examples

Create and use an ApplicationList

After had retrieved the DataArea first we get the ApplicationDataArea for my portlet:

ApplicationDataArea applicationDataArea = dataArea.getApplicationDataArea(MyPortlet.class);

Then we create a new list using the getList method which if the list don't exist create a new one:

String dataName = "MyList";
ApplicationList<String>  mylist = applicationDataArea.<String>getList(dataName);

Then we add some elements to the list. Those elements are automatically persisted by the Home Library.

 
mylist.add("data1");
mylist.add("data2");
mylist.add("data3");
mylist.add("data4");

Because the ApplicationList class implements the List interface we can use it as normal list:

for (String data:mylist){
  System.out.println("data: "+data);
}

Create and use an ApplicationMap

After had retrieved the ApplicationDataArea for my portlet create the map and put new values:

ApplicationMap<String, String> mymap = applicationDataArea.<String,String>getMap("test");
 
mymap.put("test1", "value1");
mymap.put("test2", "value2");
mymap.put("test3", "value3");
mymap.put("test4", "value4");

Because the ApplicationMap class implements the Map interface we can use it as normal map:

for (Entry<String, String> entry:mymap.entrySet()){
  System.out.println("key: "+entry.getKey()+" value: "+entry.getValue());
}

Turn off the HomeLibrary logging

The HomeLibrary logging system is under refactory, currently the tmp solution is to use:

LoggingUtil.reconfigureLogging();

This command remove all appenders from the root logger and add it a console appender with ERROR threshold.

References

Some examples source code:

HomeLibraryExamples.zip

The HomeLibrary Javadoc on software distribution site:

[3]

A not updated version of javadoc (useful when the night build don't terminate successfully):

HomeLibraryDoc.zip

Lino's HomeLibrary presentation at 5th Tcom Meeting:

[4]