Application Support Layer

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. Offering both Java and HTTP APIs, it 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.

As it is depicted in the figure above, ASL is internally organized in three main groups: session and credential management, cache, and the core functionality.

Session and Credential Management

An important part of ASL is the session and credential management. In order to consider ASL as a framework that completely supports user’s needs, it should implement its own mechanisms for providing sessions and credentials. 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 their 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.

Another significant aspect of ASL is credentials and their maintenance. 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 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. 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.

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 is planned to be 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.

Core functionality

The core functionality is composed of a set of subcomponents that pack together related functionality. Particularly, it consists of Search, Metadata, Content, Annotation, Process Execution, User Profile and Administrative functionality groups. In reality, 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 invocation. It also contains the application logic for interpreting information received by gCube and transforming it into a presentable form. Detailed description of core functionality can be found in the next paragraph.

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 GHN and a Running Instance to a specific scope.

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();
	}
}

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;

ASL JavaDocs

ASL Javadoc can be found in the ASL artifact on ETICS. Check the latest build. here