Difference between revisions of "Home Library 1.0 API"

From Gcube Wiki
Jump to: navigation, search
(→‎Architecture)
(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...")
 
(48 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
{{UnderUpdate}}
+
This page refers to Home Library 1.0 API that is not supported anymore.
−
The Home Library manage and persist the users homes.
+
  
−
==Architecture==
+
Please, use the following redirect for Home Library 2.0 API:
−
The ''user's homes'' are organized in scopes.
+
  
−
The users and the homes for a specific scope are managed by the '''HomeManager'''.
+
#REDIRECT [[Home Library 2.0 API Framework Specification]]
−
 
+
−
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===
+
−
The figure 2 illustrate the Workspace Area model.
+
−
 
+
−
[[Image:homelibrary-workspacearea-model.png|frame|center|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.
+
−
 
+
−
[[Image:homelibrary-basketitem-model.png|frame|center|Figure 3. Basket 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.
+
−
 
+
−
==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).
+
−
 
+
−
====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:
+
−
# 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 dir
+
−
# 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==
+
−
 
+
−
===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"