|
|
| (13 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 [https://gcube.wiki.gcube-system.org/gcube/index.php/RuntimeResourceClassification#Jackrabbit_Repository_Runtime_Resource jackrabbit repository 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.
| + | |
| − | | + | |
| − | <source lang="java5">
| + | |
| − | HomeManagerFactory factory = HomeLibrary.getHomeManagerFactory();
| + | |
| − | </source>
| + | |
| − | | + | |
| − | Obtained the factory you can retrieve the HomeManager:
| + | |
| − | <source lang="java5">
| + | |
| − | HomeManager manager = factory.getHomeManager();
| + | |
| − | </source>
| + | |
| − | | + | |
| − | Then we retrieve the User home:
| + | |
| − | <source lang="java5">
| + | |
| − | User user = manager.createUser(portalLogin);
| + | |
| − | Home home = manager.getHome(user,scope);
| + | |
| − | </source>
| + | |
| − | Where ''portalLogin'' is the user username used to login into the portal (for test you can use any username) and ''scope'' can be a GCUBEScope object or a GCUBEScope expression (for test you can use any expression).
| + | |
| − | | + | |
| − | At this point we can get the Workspace with his root:
| + | |
| − | <source lang="java5">
| + | |
| − | Workspace w = home.getWorkspace();
| + | |
| − | WorkspaceFolder 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 item";
| + | |
| − |
| + | |
| − | String name = WorkspaceAreaUtil.getUniqueName(nameCandidate, root);
| + | |
| − | </source>
| + | |
| − | | + | |
| − | If an item with ''My first item'' already exists, a new name ''My first item(n)'' since it not conflict with others one.
| + | |
| − | | + | |
| − | =====Create an ExternalUrl into a workspace folder=====
| + | |
| − | After had retrieved the user workspace root:
| + | |
| − | <source lang="java5">
| + | |
| − | WorkspaceFolder folder = root.createFolder("My first fidker", "This is my first folder created with the HomeLibrary");
| + | |
| − | | + | |
| − | folder.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 workspace folder=====
| + | |
| − | After had retrieved the user workspace root:
| + | |
| − | <source lang="java5">
| + | |
| − | WorkspaceFolder folder = root.createFolder("My first folder", "This is my first folder created with the HomeLibrary");
| + | |
| − | | + | |
| − | File myFile = new File("build.xml");
| + | |
| − | InputStream fileData = new FileInputStream(myFile);
| + | |
| − |
| + | |
| − | folder.createExternalFile("My External File", "This is an external file", "text/xml", fileData);
| + | |
| − |
| + | |
| − | WorkspaceTreeVisitor wtv = new WorkspaceTreeVisitor();
| + | |
| − |
| + | |
| − | wtv.visitVerbose(root);
| + | |
| − | </source>
| + | |
| − | | + | |
| − | | + | |
| − | =====Create an ExternalResourceLink into a workspace folder=====
| + | |
| − | | + | |
| − | An ExternalResourceLink item basically is a link to a resource stored by several services (for instance the [https://gcube.wiki.gcube-system.org/gcube/index.php/Storage_Management_NEW Storage Manager]). The Home Library uses plugins dedicated to retrieve the content of the resources.
| + | |
| − | | + | |
| − | After had retrieved an user workspace folder:
| + | |
| − | <source lang="java5">
| + | |
| − | folder.createExternalResourceLink("My External Resource Link", "This is an external link", "text/xml"."resourceId","plugin name");
| + | |
| − | </source>
| + | |
| − | | + | |
| − | The ''"resourceId"'' is the identifier or URI to the resources stored by several services and the'' "plugin name"'' is the name of the plugin handles the content of the resource.
| + | |
| − | | + | |
| − | ====ExternalResourceLinkPlugin====
| + | |
| − | These plugins implement the interface ''org.gcube.portlets.user.plugin.ExternalResourceLinkPlugin'' provided by the Home Library component. Conventionally the name of the plugin is the same to the class name which implements the interface.
| + | |
| − | | + | |
| − | At the moment the following plugins have been implemented:
| + | |
| − | | + | |
| − | - ''org.gcube.contentmanagement.StorageManagerResourcePlugin''. This plugin allow to retrieve the content of the resources of the [https://gcube.wiki.gcube-system.org/gcube/index.php/Storage_Management_NEW Storage Manager].
| + | |
| − | | + | |
| − | ====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]
| + | |
