Difference between revisions of "Home Library 1.0 API"

Revision as of 16:14, 1 October 2009

THIS SECTION OF GCUBE DOCUMENTATION IS CURRENTLY UNDER UPDATE.

The Home Library manage and persist the users homes.

Architecture

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).

Figure 1. Home Library Reference Architecture

Workspace Area model

The figure 2 illustrate the Workspace Area model.

Figure 2. Workspace Area model

Each element contained in a workspace area is a WorkspaceAreaItem.

There are two kind of item container: the Workspace and the Basket, both can be referred as WorkspaceFolder.

A workspace can contain one or more workspacefolder.

A basket can contain only BasketItems.

In each workspace area there is a Default Basket, a special basket that can't be deleted or moved.

The basket items are the effective user objects.

The figure 3 illustrate the BasketItem model.

Figure 3. Basket Item model

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).

Dependecies

The home library require some library to be used:

• xstream-1.3.1.jar XML serialization (XStream)
• xpp3_min-1.1.4c.jar XML serialization (XStream)
• bcprov-ext-jdk15-141.jar manipulate pdf
• iText-2.1.4.jar manipulate pdf
• ij140g.jar manipulate images

Add those libraries to your gcore installation ($GLOBUS_PATH/lib folder).

Configuration

To be used the Home Library need a folder where create a persistence dir (For test use is not necessary to configure it).

There are different way to specify the base dir where create the persistence dir:

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 dir
3. If none of preceding properties is specified the system tmp directory is used a base dir. Make attention, sometime the tmp folder is delete at system reboot, use it only for test.

Inside the base dir a home_library_persitence dir is created and used.

Using the Home Library

Retrieve an User WorkspaceArea 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).

Finally we can get the WorkspaceArea with his root:

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

How to retrieve an User WorkspaceArea from a servlet

To retrieve a WorkspaceArea for a User you can use the getWorkspaceArea static method from HomeLibrary class. This method required only the current D4ScienceSession.

WorkspaceArea wa = HomeLibrary.getUserWorkspaceArea(session);

Examples

There are some example of HomeLibrary use.

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);

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 (tmp location waiting for HL build fixing):

HomeLibraryDoc.zip

Lino's HomeLibrary presentation at 5th Tcom Meeting:

[3]