Application Support Layer
Contents
Introduction
The Application Support Layer (ASL) is a middleware between gCube Lower level Services and the gCube Presentation Layer. Its main goal is to provide a unified interface for accessing gCube and to allow application developers to deal only with how to render and present the corresponding functionality. Furthermore, ASL is responsible for covering all the application logic needed in order to fulfill users’ requirements. Since ASL aims at addressing a wide audience - not only gCube developers, it is designed to wrap gCube’s complexity by packing and interfacing standard procedures like retrieving service running instances from IS, attaching (or not) caller credential to stubs, and in general, to prepare the environment for a remote call. It should be mentioned that ASL consumers need no knowledge about where the services are running, whether a remote call is required in order to accomplish their goal, etc. In particular, ASL consists of ASL Core and ASL Extensions. ASL Core is the group of basic functionality on which developers can build their own extensions. It provides caching and session mechanisms as well as easy ways to retrieve running instances and invoke services. It also deals with security and authentication. On the other hand, ASL Extensions are libraries that extend ASL in order to cover the usage of other (new / non core) services. ASL Core functionality facilitates the development of these libraries. They aim to provide the GUI developer with a full package that will cover all the application logic so as to create the corresponding Graphical Interfaces. For each new functionality offered by gCube, a corresponding ASL Extension should be developed. Offering both Java and HTTP APIs, ASL supports multiple ways to contact and interact with gCube lower level services. In essence, ASL acts as a gateway for other technologies to access gCube advanced facilities. This means that it receives all the requests to call gCube services and, acting as a proxy, it invokes the corresponding services.
Reference Architecture
In brief, the design of ASL is motivated by the following objectives:
- To remove the application logic from the presentation layer.
- To enable external developers to create Graphical User Interfaces (GUIs) for gCube system without any knowledge of its internal design and architecture.
- To speed up gCube system’s performance by caching frequently used, and/or rarely modified resources.
- To provide an easy way to manage credentials.
- To offer a global session management that enforces interoperability and intercommunication between application components.
The aforementioned objectives and design decisions are analyzed in the following sub-sections.
As it is depicted in the figure above, ASL consists of two main sections: ASL Core and ASL Extensions. ASL core is internally organized in three main groups: session management, cache, and the core functionality. ASL extensions currently contain the packages for ASL UserProfile and ASL Search.
ASL Core Functionality
ASL Core provides the fundamentals for building a gCube Graphical Application. It is the API that ASL consumers use in order to interact with gCube. It acts as a proxy that hides complexity of several steps needed for the invocations. It also contains the application logic for interpreting information received by gCube and transforming it into a presentable form. It consists of cache, session, security, content, VRE management, commons and util components. Detailed description of core functionality can be found in the next paragraphs.
Session Management
An important part of ASL Core is the session management. In order to consider ASL as a framework that completely supports users’ needs, it should implement its own mechanisms for providing sessions. Session is of crucial importance for the presentation layer since it provides means of storing information related to each user and means of intercommunication between application components. For this reason, a Session Manager has been implemented, based on the singleton design pattern. Its role is to administrate session objects, and to provide each user with his/her session. By using it, an application component can intercommunicate with another component by storing information in the session, and reading it from the other one. In fact, session is a hash map containing name – value pairs for various properties.
Caching for Performance
Cache plays a main role within ASL. Its existence is considered essential in order to improve gCube’s performance and to give the impression to the end-user that the application layer is always ready to promptly respond to their requests. Therefore, a variety of resources that are frequently requested are cached in order to speed up response time. Depending on the type of the cached resource, different refresh and storage policies can be applied. In particular, the one can configure the expiration time of the cached resources, the maximum number of these objects in memory, whether or not to support overflow on disk, the maximum size of objects on the disk, etc. Furthermore, examples of resources that are being cached are:
- The available collections per VRE, ASL caches the names of the available collections in a hierarchical structure together with information about the available corresponding metadata, and the existence of any special kind of index, like full text, geospatial, or similarity index.
- Content information, it contains information about the digital objects, like their mime type, length, the existence of annotations over the object, the number of associated metadata, etc.
- Generic Resources, it caches generic resources from IS since they are frequently requested and yet rarely modified. Examples of such resources are the metadata presentation xslts, the record presentation xslts, etc.
- Metadata, the metadata are stored in cache so as to be retrieved quickly. In many cases, the user requests to see the metadata of a digital object in a specific schema and then he/she requests this object’s metadata in another schema. So, if the alternative metadata exist in cache, the system responses immediately.
- Profiles, user’s profile is used in many cases in order to personalize the layout based on user’s preferences. Thus, having a replica in main memory (or in the local disk) speeds up the procedure.
- Searchable fields per metadata schema, for each metadata schema the VRE administrator can define a set of fields that the user can search. Typical examples of such fields are the title, the description, and the author.
- Thumbnails, they are typically used for presentation reasons when result records are presented. They are stored as alternative representations in Content Management System, and as a result, their retrieval is a big overhead. Therefore, keeping a copy locally improves application’s performance.
Security
Another significant aspect of ASL Core is security. The gCube system is based on PKI credentials in order to authenticate and authorize users. As a result, creating, retrieving and safely keeping proxy certificates is a central goal. ASL Core transparently retrieves user’s proxy credential and stores it in the session. Additionally, depending on the security type of the active VRE (secure or not), the ASL decides whether or not to attach user’s credential on the service’s stubs in order to make a secure call.
Furthermore, ASL Security provides a user authentication mechanism independent from specific applications and authentication providers. It uses a pluggable mechanism to specify “authentication modules” used for authenticating users to the applications interacting with it. In summary, ASL consumers don’t need to have any knowledge about how security is implemented in gCube, how to retrieve credentials, make secure calls to services, etc.
Content Management
Content is of crucial importance for a Virtual Research Environment. Users expect to search, discover, manage and present the available content. Thus, it is mandatory that a number of functionalities is being provided in order to access not only the raw content, but also its alternative forms. Through ASL Core, a user can access the raw content, its alternative representations of which the most frequently requested is the thumbnail, as well as the corresponding metadata.
VRE Management
In order to manage a Virtual Research Environment, ASL Core offers a rich API so as to administer the infrastructure. Part of the functionality provided is to create/ update/ delete a Generic Resource on IS, to query IS in order to retrieve information such as running instances, available GHNs, in addition to creating / updating a VRE, and dynamically deploying a service.
ASL Extensions
ASL User Profile Extension
ASL UserProfile Extension provides additional functionality for managing user profiles. Through this library, the user can access, update, create and remove a profile. As a result, the presentation can be personalized based on information stored in user’s profile.
ASL Search Extension
ASL Search Extension supports search functionality in order to query collections and retrieve the results. Graphical User Interface can build the query step by step by first selecting the collections, then filling in the criteria, and finally submitting the query. The results will be retrieved in pages either in a personalized html format or as plain metadata. Additionally, the user can navigate through results be requesting the previous, next or first page.
Download
ASL jar can be found in the ETICS latest build.
How to use ASL
Retrieving Session
Graphical User Interface developers should use the ASL internal session in order to store information. If GUI is a Web Application (portlet, servlet, jsp etc), then the proposed way to retrieve user's session is:
D4ScienceSession d4session = SessionManager.getInstance().getD4ScienceSession(session.getId(), username);
Where session is either a portlet-session or a servlet-session, and username is the username of the logged in user.
Needed imports:
import org.gcube.application.framework.session.D4ScienceSession; import org.gcube.application.framework.session.SessionManager;
Once you have the D4SSession object, you can use ASL API to communicate with gCube infrastructure.
Querying IS
By using ISInfo class, you can directly query the IS in order to retrieve information.
Additionally, you can add / remove a GHN and a Running Instance to a specific scope, you can retrieve the profiles of the collections of a given scope, you can get the metadata-collections associated with a given collection as well as the indices associated with a collection or metadata collection.
Below you can see an example of how to query IS:
String xquery = ""; xquery = "declare namespace is = 'http://gcube-system.org/namespaces/informationsystem/registry';"+ "for $Resource in collection(\"/db/Profiles\")//Document/Data/is:Profile/Resource" + "where $Resource/ID/string() eq '" + resourceID +"' return $Resource"; D4ScienceSession d4session = SessionManager.getInstance().getD4ScienceSession(session.getId(), username); ISInfo is = new ISInfo(d4session); List<XMLResult> result = null; String transformedXML = ""; result = is.queryDIS(xquery); for (XMLResult res: result) { // Do something with the results! }
Needed imports:
import org.gcube.application.framework.api.ISInfo;
Managing Generic Resources
You can manage gCube generic resource by using the GenericResource class of ASL. Through this class you can create, update, delete and retrieve a generic resource from IS.
The sample code below represents how you can create, update and delete a generic resource:
D4ScienceSession d4session = SessionManager.getInstance().getD4ScienceSession(session.getId(), username); GenericResource gR = new GenericResource(d4session); ISGenericResource genResource = new ISGenericResource(); try { genResource.setName(SessionConstants.ScenarioSchemaInfo); genResource.setDescription("Bla foo test"); genResource.setBody("<DL>the dl :-)</DL>"); } catch (FileNotFoundException e) { e.printStackTrace(); } catch (Exception e) { e.printStackTrace(); } try { gR.createGenericResource(genResource); // Creating the generic resource!!! genResource.setDescription("this is different description!!!"); // Changing the description (locally) gR.updateDiligentGenericResourceByID(genResource); // Updating the generic resource on IS gR.remove(genResource); // Removing the generic resource } catch (RemoteException e) { e.printStackTrace(); } }
The sample code below represents how you can retrieve information for generic resources:
/* Get the "name - id" pairs of the available generic resources */ D4ScienceSession d4session = SessionManager.getInstance().getD4ScienceSession(session.getId(), username); LinkedHashMap<String,String> existingGRs = new LinkedHashMap<String,String>(); GenericResource gResources = new GenericResource(d4session); List<Pair> pairs = gResources.getAvailableGenericResourceNames(); for (int i=0; i<pairs.size(); i++) { String GRID = pairs.get(i).getValue(); String GRName = pairs.get(i).getName(); existingGRs.put(GRID, GRName); }
/* Retrieve the list of the generic resources with the given name / id */ D4ScienceSession d4session = SessionManager.getInstance().getD4ScienceSession(session.getId(), username); GenericResource gResources = new GenericResource(d4session); List<ISGenericResource> genericResources = gResources.getGenericResourceByID(“resourceId”); genericResources = gResources.getGenericResourceByName(“resourceName”);
Needed imports:
import org.gcube.application.framework.api.GenericResource; import org.gcube.application.framework.api.model.ISGenericResource;
A sample generic resource:
<?xml version="1.0" encoding="UTF-8"?> <Resource> <ID/> <Type>GenericResource</Type> <Profile> <Name/> <Description/> <Body> <DL geospatial="false" name="/gcube/devsec"> <collections name="Environment Documents" description="Environment Documents" shortname="docs"> <collection name="FAO test collection" description="FOA" reference="www.fao.org/documents/" shortname="faocdr"/> </collections> </DL> </Body> </Profile> </Resource>
Note:
Generic Reources are cached so as to avoid multiple calls to IS in order to retrieve the same resource many times.
Getting available Collections & Search Queries
In order to retrieve the available collections regarding the active VRE, or to retrieve a search query, you have to use the SearchHelper class.
The collections are returned in a hierarchical way. An array of linked lists contains the collections that are organized as level 2 tree. Each list contains a group of collections that are logically packed together. The first element of the list is always the name of the group (together with the description of the group etc). The rest elements represent the actual collections.
By using SearchHelper class you can also retrieve the available metadata schemata for querying collections in addition to the search fields that each of them offers. For each metadata schema, a list of the searchable fields is stored in a hasmap having as key the schema name.
How to retrieve available collections, search query and search fields per metadata schema:
D4ScienceSession d4session = SessionManager.getInstance().getD4ScienceSession(session.getId(), username); SearchHelper searchH = new SearchHelper(d4session); // Retrieving the available collections: List<CollectionInfo>[] colls = searchH.getAvailableCollections(); if(colls != null) { for(int i=0; i<colls.length; i++) { System.out.println("+ " + colls[i].get(0).getName()); // group name for(int j=1; j< colls[i].size(); j++) { System.out.println("|-+ " + colls[i].get(j).getName()); // collection name } } } // Retrieving the first query (from a set of open queries): searchH.getQuery(0); // Retrieving the searchable fields for each schema: HashMap<String, List<SearchField>> schemata = searchH.getSchemataInfo(); for(String schema: schemata.keySet()) { List<SearchField> fields = schemata.get(schema); System.out.println("++++++++++ Searchable fields for schema: " + schema + "++++++++++"); for(SearchField fld : fields) { System.out.println(fld.name); } }
Needed imports:
import org.gcube.application.framework.search.library.helper.SearchHelper; import org.gcube.application.framework.search.library.model.CollectionInfo; import org.gcube.application.framework.search.library.model.SearchField;
Building & Submitting a Search Query
Once having created or obtained the query object you can form or update it, performing operations on the selected collections, the criteria set by the user, the selected schema, the condition type and the sorting order.
D4ScienceSession d4session = SessionManager.getInstance().getD4ScienceSession(session.getId(), username); SearchHelper sHelper = new SearchHelper(d4session); /* Refresh the information for the available collections */ // The information about the collections is retrieved directly from the gCube system shelper.refreshAvailableCollections(); // Get the current query group QueryGroup queryGroup = sHelper.getActiveQueryGroup(); // Get the first query of the current group. Query queryObj = queryGroup.getQuery(DefaultQuery); /* Add new collections to the selected ones */ queryObj.selectCollections(collections, true, session); /* Add / remove a new criterion to the query */ queryObj.addCriterion(new Criterion(name,"")); queryObj.removeCriterion(searchFieldIntegerNo) /* Reset all the current criteria */ queryObj.reset(); /* Get the selected real collections (the selected collections without the collection groups) */ List<String>selectedCollections = queryObj.getSelectedRealCollections(); /* Get the selected schema (The schema name and language the user has selected */ SchemataInfos schemaInfo = queryObj.getSelectedSchemaInfos(); String selectedSchema[][] = new String[1][2]; selectedSchema[0][0] = schemaInfo.getName(); selectedSchema[0][1] = schemaInfo.getLanguage(); /* Get / set the current selected condition type */ queryObj.setOperator(Operator.AND); //or Operator.OR Operator op = queryObj.getOperator(); /* Get the fields for the selected collection and schema */ List<SearchField> sFields = queryObj.getAvailableSearchFields(); // searchable fields List<String> browsableFields = queryObj.getAvailableBrowseFields(); // browsable fields List<String> sortFields = queryObj.getAvailableSortFields(); //sortable fields /* Update a crierion */ List<Criterion> criteria = queryObj.getCriteria(); queryObj.updateCriterionName(internalNo, newName); //update a criterion name queryObj.updateCriterionValue(internalNo, newValue); //update a criterion value
Using the asl session you can set the current active query group, store and retrieve previous queries to update them performing the above operations. In this way you can achieve intercommunication between your application components and reuse previous stored information while the search is taking place and the user changes his/her search preferences.
Submit a search Query
Three types of search can be performed through ASL: Simple Search, Advanced Search and Browsing of the collections. For each type of search there is a corresponding way for forming and sumbitting the query. In the examples below the three types of query submissions are displayed:
- Submit a Simple Query
D4ScienceSession d4session = SessionManager.getInstance().getD4ScienceSession(session.getId(), username); SearchHelper shelper = new SearchHelper(d4session); QueryGroup queryGroup = shelper.getActiveQueryGroup(); Query queryObj = queryGroup.getQuery(DefaultQuery); queryObj.setTerm(fts); //The keyword to search for session.setAttribute(SessionConstants.activePresentationQueryNo, new Integer(shelper.getActiveQueryGroupNo())); queryObj.search(session, true); //set second parameter to true, indicating the search is simple int id = shelper.createQuery(shelper.getActiveQueryGroupNo()); shelper.setActiveQueryGroup(id);
- Submit an Advanced Query
D4ScienceSession d4session = SessionManager.getInstance().getD4ScienceSession(session.getId(), username); SearchHelper shelper = new SearchHelper(d4session); QueryGroup queryGroup = shelper.getActiveQueryGroup(); Query queryObj = queryGroup.getQuery(DefaultQuery); queryObj.setSortBy(sortby); //optional queryObj.setOrder(Order.ASC); // or Order.DESC session.setAttribute(SessionConstants.activePresentationQueryNo, new Integer(shelper.getActiveQueryGroupNo())); // If the user wants to search per collection, separate queries must be constructed in the query group each for one collection, // and they must be separately submitted queryObj.search(session, false); //query submission // After performing a search create a new query. It will actually clone the current query int id = shelper.createQuery(shelper.getActiveQueryGroupNo()); shelper.setActiveQueryGroup(id);
- Submit a Browse Query
D4ScienceSession d4session = SessionManager.getInstance().getD4ScienceSession(session.getId(), username); SearchHelper shelper = new SearchHelper(d4session); QueryGroup queryGroup = shelper.getActiveQueryGroup(); Query queryObj = queryGroup.getQuery(DefaultQuery); queryObj.setSortBy(sortBy); queryObj.setOrder(Order.ASC); // or Order.DESC // browse the contents of the collection queryObj.setDistinct(false); // or browse a specific field of a collection (distinct values) queryObj.setDistinct(true); session.setAttribute(SessionConstants.activePresentationQueryNo, new Integer(shelper.getActiveQueryGroupNo())); queryObj.browse(session); int id = shelper.createQuery(shelper.getActiveQueryGroupNo(), false); shelper.setActiveQueryGroup(id);
Manage User Profile
Through ASL you can create and retrieve the user profile. Using the ASL session you can store many of the user's preferences in order for them to be quickly retrieved. In the code bellow you can see some examples of how to get and read the user's profile.
D4ScienceSession d4session = SessionManager.getInstance().getD4ScienceSession(session.getId(), username); UserProfile userProfile = new UserProfile(d4session); // Invoke the createResource method. If there is no profile, it creates a new one for the user. userProfile.createUserProfile(username);
/* Get specific elements from the user profile */ //get all the xslts String[] prXSLTs = userProfile.getElement(username, "/userprofile/preferences/xslts/presentationxslt/xslt"); //get the language the user has selected String lang = userProfile.getElementValue(username, "/userprofile/preferences/defLanguage");
Manage Collections and Digital Objects
Through the classes DigitalObject and Collection, ASL supports the retrieval or creation and storage of digital objects in CMS and collections in COLMS. Below you can see examples of usage of their methods:
/* Retrieve or Create a Collection */ D4ScienceSession d4session = SessionManager.getInstance().getD4ScienceSession(session.getId(), username); String colId = new String(); // find out if a collection with this name already exists colId = Collection.getCollectionByName(collectionName, d4session); if (colId == null) colId = Collection.createCollection(collectionName, d4session, false); //do something with the colId
/* Retrieve and Update a Digital Object or Create a new Digital Object containing text in XML language */ String d_o = new String(); d_o = DigitalObject.findObjectByName(vreName, colId, d4session); if (d_o == null) { // create the object and store it DocumentBuilderFactory dbfac = DocumentBuilderFactory.newInstance(); DocumentBuilder docBuilder = null; try { docBuilder = dbfac.newDocumentBuilder(); } catch (ParserConfigurationException e) { //do something with exception } byte content[] = null; Document doc = docBuilder.newDocument(); // create the document // … // create string from xml tree String nodeString; TransformerFactory tFactory = TransformerFactory.newInstance(); Transformer transformer = null; try { transformer = tFactory .newTransformer(); } catch (TransformerConfigurationException e) { // do something with exception } transformer.setOutputProperty(“omit-xml-declaration”,”yes”); StringWriter sw = new StringWriter(); StreamResult result = new StreamResult(sw); DOMSource source = new DOMSource(doc); try { transformer.transform(source, result); } catch (TransformerException e) { //do something with exception } nodeString = sw.getBuffer().toString(); content = nodeString.getBytes(); ByteArrayInputStream inputStr = new ByteArrayInputStream(content); String mimeType = “plain/text”; DigitalObject dobj = DigitalObject.createNewDigitalObject(colId, inputStr, vreName, d4session, mimeType); } // retrieve and update the content else { DigitalObject dobj = new DigitalObject(d4session, d_o, colId); InputStream cont = dObj.getObject(); if (cont != null) { DocumentBuilderFactory dfactory = DocumentBuilderFactory.newInstance(); Document doc = null; byte content[] = null; try { doc = dfactory.newDocumentBuilder().parse(cont); } catch (SAXException e) { // do something with exception } catch (IOException e) { //do something with exception } catch (ParserConfigurationExcetpion e) { //do something with exception } // update the document … // create string from xml tree … // update the content dObj.updateContent(d4session, content); } }
When you have created a DigitalObject you can get information about it (about its name, title, schema, rank, available schemata, metadata, schema languages, mime type, primary roles, secondary roles, thumbnail, html representation) using the equivalent class methods. In the example below, you can see how you can retrieve the alternative representations for a digital object:
HashMap<String, List<String>> primaryRoles = myDigitalObject.getPrimaryRoles(); List<String> alternatives = primaryRoles.get("contentmanagement:is-represented-by");
How to consider an ASL Extension
ASL Extensions are libraries that extend ASL in order to cover usage of other (new/ non core) services. ASLCore functionality facilitates the development of these libraries by offering standard ways to deal with cache, security and session. The aim of building ASL extensions is to provide the GUI developer with a full package that will cover all the application logic so as to create the corresponding Graphical Interfaces. In order to create an ASL Extension you should follow some basic guidelines that are listed below:
- Offer simple interfaces. For example, if you want to retrieve the names of the existing collections, provide a method String[] getCollections()
- In order to get the RIs of a service, use the class RIsManager (package: org.gcube.application.framework.core.cache), like the example below:
/* **** Retrieving RIs for a service **** */ EndpointReference[] modelerURIs; ISCache cache = RIsManager.getInstance().getISCache(session.getScope()); modelerURIs = cache.getEPRsFor(“VREManagement”, “VREModeler”, SrvType.FACTORY.name());
- Hide all the gCube complexity, like invoking a service, contacting IS, dealing with security, etc. In the example below, you can see how you can make a remote call to a service:
/* **** Preparing for a Remote Call **** */ ModelerFactoryPortType mFPType = null; ModelerFactoryServiceAddressingLocator mFSLocator = new ModelerFactoryServiceAddressingLocator(); //retrieving randomly one of the available EPRs of VRE modeler service serviceEPR = modelerURIs[new Random().nextInt(modelerURIs.length)]; //applying security (and setting scope etc) to the service port-type mFPType = ServiceConextManager.applySecurity(mFSLocator.getModelerFactoryPortTypePort(serviceEPR), session); // … make an actual call to VRE modeler service
Needed imports:
org.gcube.application.framework.core.cache.RIsManager org.gcube.commons.is.cache.ISCache org.gcube.application.framework.core.security.ServiceContextManager
- If you need information about the user, the scope etc, you should add the D4ScienceSession as a parameter in the constructor (as a protected member of your class). For example, see the following constructor with a D4ScienceSession:
public class SearchHelper implements SearchInfoI { D4ScienceSession session; Public SearchHelper(D4ScienceSession session) { this.session = session; } }
- Make use of the caches in order to improve gCube’s performance and to give the impression that the application layer is always ready to promptly respond to the requests. You can also store to the session information that is frequently retrieved in order to have direct access to it whenever it’s needed. In the example below you can see how the retrieval of a cached object can be performed:
/* **** Retrieving a cached object **** */ public List<CollectionInfo>[] getAvailableCollections() { List<CollectionInfo>[] collections = (List<CollectionInfo>[])session.getAttribute(SessionConstants.Collections); if(collections == null) { //Retrieve Available Collections from cache: collections = (List<CollectionInfo>[]) CachesManager.getInstance().getCollectionCache().get(session.getScopeName()).getValue(); session.setAttribute(SessionConstants.Collections, collections); } return collections; }
Needed imports:
org.gcube.application.framework.core.cache.CachesManager
ASL JavaDocs
ASL Javadoc can be found in the ASL artifact on ETICS. Check the latest build. here