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. 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 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.

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;

ASL JavaDocs

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