Difference between revisions of "Home Library 1.0 API"

From Gcube Wiki
Jump to: navigation, search
(→‎Configuration)
(Replaced content with "This page refers to Home Library 1.0 API that is not supported anymore. Please, use the following redirect for Home Library 2.0 API: #REDIRECT Home Library 2.0 API Fra...")
 
(32 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
The Home Library manage and persist the users homes.
+
This page refers to Home Library 1.0 API that is not supported anymore.
  
−
==Architecture==
+
Please, use the following redirect for Home Library 2.0 API:
−
The Home Library is define through an API interface ('''HomeLibrary''' project).  
+
  
−
Currently there are two API implementation:
+
#REDIRECT [[Home Library 2.0 API Framework Specification]]
−
* '''HomeLibraryFS''': an HomeLibrary implementation based on FileSystem and DataBase instance.
+
−
* '''HomeLibraryJCR''': an HomeLibrary implementation based on JCR 2.0 (Java Content Repository [http://jcp.org/en/jsr/detail?id=283 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.
+
−
 
+
−
[[Image:homelibrary-architecture.png|frame|center|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.
+
−
 
+
−
[[Image:homelibrary-workspacearea-model.png|frame|center|Figure 2. Workspace Item model]]
+
−
 
+
−
====Data Area model====
+
−
The figure 4 illustrate the Data Area model.
+
−
 
+
−
[[Image:homelibrary-dataarea-model.png|frame|center|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 [[relative page|Home Library (Test suite)]].
+
−
 
+
−
==Setup the Home Library==
+
−
===Installation===
+
−
To use the HomeLibrary you first need the HomeLibrary downloadable from:
+
−
* [https://grids16.eng.it/BuildReport/list/Recent_Builds] last night build
+
−
* [http://software.d4science.research-infrastructures.eu/] 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:
+
−
# set the ''HOME_LIBRARY_PERSISTENCE_DIR'' environment variable
+
−
# set the system property ''catalina.base'' (generically set by Tomcat), then the "catalina.base/webapps/usersArea" is used a base directory
+
−
# 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.
+
−
 
+
−
<source lang="java5">
+
−
Home home = HomeLibrary.getUserHome(session);
+
−
</source>
+
−
 
+
−
If you need only the WorkspaceArea you can use the getWorkspaceArea static method:
+
−
<source lang="java5">
+
−
WorkspaceArea wa = HomeLibrary.getUserWorkspaceArea(session);
+
−
</source>
+
−
 
+
−
If you need only the DataArea you can use the getDataArea static method:
+
−
<source lang="java5">
+
−
DataArea da = HomeLibrary.getUserDataArea(session);
+
−
</source>
+
−
 
+
−
===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.
+
−
<source lang="java5">
+
−
HomeManagerFactory factory = HomeLibrary.getHomeManagerFactory();
+
−
</source>
+
−
 
+
−
Obtained the factory you can retrieve the HomeManager for a specified scope:
+
−
<source lang="java5">
+
−
HomeManager manager = factory.getHomeManager(scope);
+
−
</source>
+
−
Where ''scope'' can be a GCUBEScope object or a GCUBEScope expression (for test you can use any expression).
+
−
 
+
−
Then we retrieve the User home:
+
−
<source lang="java5">
+
−
User user = manager.createUser(portalLogin);
+
−
Home home = manager.getHome(user);
+
−
</source>
+
−
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:
+
−
<source lang="java5">
+
−
WorkspaceArea wa = home.getWorkspaceArea();
+
−
Workspace root = wa.getRoot();
+
−
</source>
+
−
 
+
−
or the DataArea:
+
−
<source lang="java5">
+
−
DataArea da = home.getDataArea(session);
+
−
</source>
+
−
 
+
−
 
+
−
 
+
−
===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):
+
−
<source lang="java5">
+
−
WorkspaceTreeVisitor wtv = new WorkspaceTreeVisitor();
+
−
wtv.visitSimple(root);
+
−
wtv.visitVerbose(root);
+
−
</source>
+
−
 
+
−
There is a simple output:
+
−
<source lang="text">
+
−
/[root]
+
−
/{My Default Basket}
+
−
/{My first basket}
+
−
/MyUrl
+
−
</source>
+
−
 
+
−
There is the verbose output;
+
−
<source lang="text">
+
−
 
+
−
/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
+
−
 
+
−
</source>
+
−
 
+
−
=====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.
+
−
 
+
−
<source lang="java5">
+
−
String nameCandidate = "My first basket";
+
−
+
−
String name = WorkspaceAreaUtil.getUniqueName(nameCandidate, root);
+
−
</source>
+
−
 
+
−
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.
+
−
 
+
−
<source lang="java5">
+
−
Basket defaultBasket = workspaceArea.getDefaultBasket();
+
−
</source>
+
−
 
+
−
=====Create an ExternalUrl into a basket=====
+
−
After had retrieved the user workspace root:
+
−
<source lang="java5">
+
−
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);
+
−
</source>
+
−
 
+
−
=====Create an ExternalFile into a basket=====
+
−
After had retrieved the user workspace root:
+
−
<source lang="java5">
+
−
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);
+
−
</source>
+
−
 
+
−
=====Create a GPOD-Link into the default basket=====
+
−
After had retrieved the user workspace root:
+
−
<source lang="java5">
+
−
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);
+
−
</source>
+
−
 
+
−
====DataArea examples====
+
−
 
+
−
=====Create and use an ApplicationList=====
+
−
After had retrieved the DataArea first we get the ApplicationDataArea for my portlet:
+
−
 
+
−
<source lang="java5">
+
−
ApplicationDataArea applicationDataArea = dataArea.getApplicationDataArea(MyPortlet.class);
+
−
</source>
+
−
Then we create a new list using the getList method which if the list don't exist create a new one:
+
−
<source lang="java5">
+
−
String dataName = "MyList";
+
−
ApplicationList<String>  mylist = applicationDataArea.<String>getList(dataName);
+
−
</source>
+
−
Then we add some elements to the list. Those elements are automatically persisted by the Home Library.
+
−
<source lang="java5">
+
−
mylist.add("data1");
+
−
mylist.add("data2");
+
−
mylist.add("data3");
+
−
mylist.add("data4");
+
−
</source>
+
−
Because the ApplicationList class implements the List interface we can use it as normal list:
+
−
<source lang="java5">
+
−
for (String data:mylist){
+
−
  System.out.println("data: "+data);
+
−
}
+
−
</source>
+
−
 
+
−
=====Create and use an ApplicationMap=====
+
−
After had retrieved the ApplicationDataArea for my portlet create the map and put new values:
+
−
 
+
−
<source lang="java5">
+
−
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");
+
−
</source>
+
−
 
+
−
Because the ApplicationMap class implements the Map interface we can use it as normal map:
+
−
<source lang="java5">
+
−
for (Entry<String, String> entry:mymap.entrySet()){
+
−
  System.out.println("key: "+entry.getKey()+" value: "+entry.getValue());
+
−
}
+
−
</source>
+
−
 
+
−
 
+
−
===Turn off the HomeLibrary logging===
+
−
 
+
−
The HomeLibrary logging system is under refactory, currently the tmp solution is to use:
+
−
<source lang="java5">
+
−
LoggingUtil.reconfigureLogging();
+
−
</source>
+
−
 
+
−
This command remove all appenders from the root logger and add it a console appender with ERROR threshold.
+
−
 
+
−
==References==
+
−
Some examples source code:
+
−
 
+
−
[[Media:HomeLibraryExamples.zip|HomeLibraryExamples.zip]]
+
−
 
+
−
The HomeLibrary Javadoc on software distribution site:
+
−
 
+
−
[http://software.d4science.research-infrastructures.eu/PackagesServlet?version=org.gcube.HEAD&title=development]
+
−
 
+
−
A not updated version of javadoc (useful when the night build don't terminate successfully):
+
−
 
+
−
[[Media:HomeLibraryDoc.zip|HomeLibraryDoc.zip]]
+
−
 
+
−
Lino's HomeLibrary presentation at 5th Tcom Meeting:
+
−
 
+
−
[http://bscw.research-infrastructures.eu/bscw/bscw.cgi/d107608/06.%20HomeLibrary.ppt]
+

Latest revision as of 17:54, 7 July 2016

This page refers to Home Library 1.0 API that is not supported anymore.

Please, use the following redirect for Home Library 2.0 API:

  1. REDIRECT Home Library 2.0 API Framework Specification
Retrieved from "https://wiki.gcube-system.org/index.php?title=Home_Library_1.0_API&oldid=25284"