|
|
| (52 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''').
| + | |
| − | | + | |
| − | [[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]]
| + | |
| − | | + | |
| − | ==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>
| + | |
| − | | + | |
| − | | + | |
| − | | + | |
| − | ===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]
| + | |
