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 a session mechanism 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 also facilitates ASL extension developers by dealing with security issues and user credentials, scoped services calls, session management and retrieval of generic resources.

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.

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.

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. In order to retrieve the needed information it contacts the UserProfileAccess service, the ProfileAdministration service and it gets the necessary resources from IS. 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. It contacts the SearchMaster and IS in order to retrieve information about the collections, joining the knowledge acquired from their dynamic and static configuration. 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. Then the query is submitted to the SearchMaster in order to be executed. 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.

ASL Content Management Extension

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. ASL Content Management extension provides functionality for managing the content. Through this library, 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. In addition using this extension the user can also create a new digital object or update the content of an existing one. Furthermore, it provides functionality for managing collections. Contacting the CMS service, this extension offers an interface for creating or deleting collections and adding or removing elements from them.

ASL VRE Management Extension

In order to manage a Virtual Research Environment, ASL VRE Management extension 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.

Home Library

http://technical.wiki.d4science.research-infrastructures.eu/documentation/index.php/Home_Library

Cacheing 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, 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 cached are:

• The available collections per VRE: ASL Content extension 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. This cache is implemented by ASL Content extension.

• 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. This cache is placed in ASL Core, as the generic resources are frequently asked, their use is destinated for a large variety of reasons and they should be provided by the core unit of ASL.

• 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. This cache is also implemented by ASL Content extension.

• 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. This caching mechanism is placed inside ASL User Profile extension.

• 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. This cache is developed in ASL Search Extension.

• 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. The caching of the thumbnails is implemented inside ASL Content extension.

Download

ASL jar can be found in the ETICS latest build.

How to use ASL

ASL Core - Retrieving Session

Graphical User Interface developers should use the ASL internal session in order to store information. In order to use the ASL's session, you need to take an instance of the SessionManager object that is based on the Singleton resource pattern. Through this instance a unique session for each user can be retrieved. If GUI is a Web Application (portlet, servlet, jsp etc), then the proposed way to retrieve user's session is:

ASLSession aslSession = SessionManager.getInstance().getASLSession(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.ASLSession;
import org.gcube.application.framework.session.SessionManager;

Once you have the ASLSession object, you can use ASL API to communicate with gCube infrastructure.

VRE Management extension - 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";
ASLSession aslSession = SessionManager.getInstance().getASLSession(session.getId(), username);
ISInfo is = new ISInfo(aslSession);
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;

ASL Core - 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:

ASLSession aslSession = SessionManager.getInstance().getASLSession(session.getId(), username);
GenericResource gR = new GenericResource(aslSession);
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 */
 
ASLSession aslSession = SessionManager.getInstance().getASLSession(session.getId(), username);
 
LinkedHashMap<String,String> existingGRs = new LinkedHashMap<String,String>();
GenericResource gResources = new GenericResource(aslSession);
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 */
 
ASLSession aslSession = SessionManager.getInstance().getASLSession(session.getId(), username);
GenericResource gResources = new GenericResource(aslSession);
 
List<ISGenericResource> genericResources = gResources.getGenericResourceByID(“resourceId”);
 
genericResources = gResources.getGenericResourceByName(“resourceName”);

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.

Search Extension - 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:

ASLSession aslSession = SessionManager.getInstance().getASLSession(session.getId(), username);
 
 
SearchHelper searchH = new SearchHelper(aslSession);
// 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
		}
	}
}
 
 
/** The queries are organized in "query groups". 
 * A query group actually contains the main query, but more queries can be added later
 * to the group that are corresponding to the initial query. For example when a user submits
 * a query and chooses to perform the search "by collection", then a set of queries will be
 * performed, one for every different collection. All those queries will belong to the same
 * query group. When asking for the "default" query, you actually get the first (and maybe only)
 * query of the group */
 
// Retrieving the first query (from a set of open queries):
// Get the current query group
QueryGroup queryGroup = sHelper.getActiveQueryGroup();
// Get the first query of the current group. 
Query queryObj = queryGroup.getQuery(DefaultQuery); 
 
 
// 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;

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

ASLSession aslSession = SessionManager.getInstance().getASLSession(session.getId(), username);
SearchHelper sHelper = new SearchHelper(aslSession);
 
 
/* 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 */
/* Set second parameter to true if you want to select the collections or false if you want to deselect them */
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

ASLSession aslSession = SessionManager.getInstance().getASLSession(session.getId(), username);
SearchHelper shelper = new SearchHelper(aslSession);
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

ASLSession aslSession = SessionManager.getInstance().getASLSession(session.getId(), username);
SearchHelper shelper = new SearchHelper(aslSession);
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

ASLSession aslSession = SessionManager.getInstance().getASLSession(session.getId(), username);
 
SearchHelper shelper = new SearchHelper(aslSession);
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);

User Profile Extension - 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.

ASLSession aslSession = SessionManager.getInstance().getASLSession(session.getId(), username);
UserProfile userProfile = new UserProfile(aslSession);
 
// 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");

Content Extension - Manage Collections and Digital Objects

Through the classes DigitalObject and Collection, ASL Content Management extension 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 */
ASLSession aslSession = SessionManager.getInstance().getASLSession(session.getId(), username);
String colId = new String();
// find out if a collection with this name already exists
colId = Collection.getCollectionByName(collectionName, aslSession);
if (colId == null) 
	colId = Collection.createCollection(collectionName, aslSession, 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, aslSession);
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, aslSession, mimeType);
}
// retrieve and update the content
else {
	DigitalObject dobj = new DigitalObject(aslSession, 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(aslSession, 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

When is an ASL Extension needed

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. Practically, an ASL extension is needed when:

• A new functionality is added to gCube (e.g. a new service)
• The existing ASL Extensions do not cover the functionality requested by users.
• Part of a functionality needs to be offered in an alternative way than the existing one (e.g. offer personalized results, http api, etc)

Conventions

• When creating a project destinated for an ASL Extension, it is recommended to name it with the following pattern:

"applicationSupportLayerNameOfTheExtension"

, where you can replace the "NameOfTheExtension" string with the name of your extension. For example the projects for the UserProfile and Search extensions are named respectively: applicationSupportLayerUserProfile and applicationSupportLayerSearch.

• When creating a package inside an ASL Extension project, you should name it using the following naming convention:

org.gcube.application.framework.extensionRelatedName.packageRelatedName

For example the names of two of the packages inside Search extension project are:

org.gcube.application.framework.search.exception
org.gcube.application.framework.search.library.model

• Another convention used for the API of ASL is the use of a package that includes the interface and a separate one for the implementation. This pattern is used in both ASL core and the existing ASL extensions. For example, in UserProfile extension the package "org.gcube.application.framework.userprofiles.library" includes the interface of the classes that are implemented in the package "org.gcube.application.framework.userprofiles.library.impl".

Basic Guidelines

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()
• Use the functionality already offered by ASL core and the existing ASL extensions.
• 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;
	}
}

• 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 but also in the Distribution Site visiting the following links: http://node1.p.d4science.research-infrastructures.eu:8888/maven/ApplicationSupportLayer/ASLCore/1/00/00/ASLCore/1.00.04/doc/api/index.html (stable release)

http://dlib05.isti.cnr.it/maven/ApplicationSupportLayer/ASLCore/1/00/00/ASLCore/1.00.04/doc/api/index.html (development release)

Check the latest build. here

ASL HTTP API

HTTP API offers a subset of Java API, mostly the fundamental functionality needed by simple end-users. It is planned to be extended based on users’ needs and requirements. It consists of a set of servlets that support both GET and POST http methods depending on what functionality is requested. The functionality offered by this api concerns four sections:

• User Authentication

• VO/VREs Functionality

• Content Functionality

• Search Functionality

In detail, it currently provides support for the following functionality:

User Authentication

• Login - Logout

The corresponding servlet receives the user’s credential (username – password) and communicates with LDAP in order to authenticate the user. It makes use of status codes and HTTP headers to manage the security policy. In case of denied credentials it returns an SC_UNAUTHORIZED status code to the client. Both BASIC and Form – based authentication methods are implemented to this end. In order to login, using ASL HTTP API, a GET or POST request needs to be made to the servlet with the name “LoginHandler”.

With the basic authorization scheme, the Authorization header contains the string of "username:password" encoded in Base64. For example, the username of "webmaster" with the password "try2guess" is sent in an Authorization header with the value:

 BASIC d2VibWFzdGVyOnRyeTJndWVTUw"

Here is an example of a URL for a login request: https://hostname/applicationSupportLayerHttp/LoginHandler

• Session Tracking

ASL HTTP makes use of the built in session tracking mechanisms of the servlets. Consequently, the user’s session can be tracked either with the use of persistent cookies, where the session ID is saved on the client in a cookie called JSESSIONID, or with URL rewriting. URL rewriting can be used by clients that don’t support cookies by sending the sessionID as part of a rewritten URL, encoded using a jsessionid path parameter. The session is returned once the user logs in the system inside an XML response, and all the following URL – encoded requests must contain it. By offering a session tracking mechanism, ASL allows the user to make subsequent requests without having to log in every time he asks for a resource.

An example of an XML response returning the session id is presented bellow:

 
<?xml version="1.0" encoding="UTF-8"?>
    <SessionID>
        <jsessionid>6751BF9588491D6EB853096C84B3671F</jsessionid>
    </SessionID>

VO/VREs Functionality

• Show Available VO/VREs

Once logged in, the user can see the VO/VREs to which he/she has access. To this end, the servlet reads from VOMS the groups for the user and then shows all the VREs the user can access and all the VOs to which the user has the role of VO-Admin or VRE-Manager or VRE-Designer or Production Support. In order to ask for the available VO/VREs, the client needs to make a GET request to the “ShowVREs” servlet of ASL HTTP API. An xml file, listing the information about the VO/VREs is sent as a response to the user.

• • Parameters needed: none

An example of an XML response, listing the available VO/VREs is presented bellow:

<?xml version="1.0" encoding="UTF-8"?>
<VOs-VREs>
	<VRE>/d4science.research-infrastructures.eu/EM/Demo</VRE>
	<VRE>/d4science.research-infrastructures.eu/FCPPS/Demo</VRE>
	<VO>/d4science.research-infrastructures.eu/EM</VO>
</VOs-VREs>

• Login to a VO/VRE:

In order to be able to see the available content of a VO/VRE, a user needs to log into it. To that end, a servlet that logs the user to a virtual research environment is created. A GET method must be made by the client, passing as a value to a “scope” parameter, the name of the corresponding VO/VRE.

   *Parameters needed: scope (the VO/VRE we need to access)
   *Response: An HTTP OK status code or an HTTP error status code