Database resource

Introduction

Database resources are heavily used in the gCube infrastructure, however developers are using several ways to represent them on the Information System.

This page describe a database resource model and promotes a client library to be used in order to retrieve databases from the IS.

Model

Database resource model is based on the Runtime Resource resource. The guidelines are explained through an example:

<Resource version="0.4.x">
   <ID>15398010-c13a-11e2-a1ec-f54c9ec8d8f1</ID>
   <Type>RuntimeResource</Type>
   <Scopes>
      <Scope>/gcube/devsec</Scope>
   </Scopes>
   <Profile>
      <Category>Database</Category>
      <Name>TabularData Database</Name>
      <Description />
      <!-- Specify database technology name and version -->
      <Platform>
         <Name>PostgreSQL</Name>
         <Version>9</Version>
         <MinorVersion>2</MinorVersion>
         <RevisionVersion>4</RevisionVersion>
         <BuildVersion>0</BuildVersion>
      </Platform>
      <RunTime>
         <HostedOn>pc-fortunati.isti.cnr.it:5432</HostedOn> <!-- This field must include the hostname and the port through wich the DB service is accessible -->
         <GHN UniqueID="" />
         <Status>READY</Status>
      </RunTime>
      <AccessPoint>
         <Description>Tabular Data Database endpoint for data (tables) storage (Admin user)</Description>
         <Interface>
            <!-- The endpoint EntryName should give a hint of the database being point and the privileges granted within the credentials -->
            <!-- 
                As a rule of thumb please follow this naming convention:
                "${DBName}-${Privileges}" 
                where:
                * ${DBName} is a name that describe the DB
                * ${Privileges} describe the privileges granted with the account provided. 
-->
            <Endpoint EntryName="Data-Admin">jdbc:postgresql://pc-fortunati.isti.cnr.it:5432/tabulardata</Endpoint>
         </Interface>
         <AccessData>
            <Username>luigi</Username>
            <Password>2cf1YRdE5TeiuhQpZUuAOw==</Password> <!-- Passwords are encrypted. In order to decrypt them you should have the scope symm key on your classpath. Refer to common-encryption for further details. -->
         </AccessData>
         <!-- An additional number of optional properties can be embedded within the endpoint -->
         <Properties>
            <Property>
               <Name>driver</Name>
               <Value encrypted="false">org.postgresql.Driver</Value>
            </Property>
         </Properties>
      </AccessPoint>
      <AccessPoint>
         <Description>Tabular Data Database endpoint for data (tables) storage (Unprivileged user)</Description>
         <Interface>
            <Endpoint EntryName="Data-User">jdbc:postgresql://pc-fortunati.isti.cnr.it:5432/tabulardata</Endpoint>
         </Interface>
         <AccessData>
            <Username>client</Username>
            <Password>CSnMl38Vjfs7+2KYRG9b/g==</Password>
         </AccessData>
         <Properties>
            <Property>
               <Name>driver</Name>
               <Value encrypted="false">org.postgresql.Driver</Value>
            </Property>
         </Properties>
      </AccessPoint>
      <AccessPoint>
         <Description>Tabular Data Database endpoint for metadata storage (Admin user)</Description>
         <Interface>
            <Endpoint EntryName="Metadata-Admin">jdbc:postgresql://pc-fortunati.isti.cnr.it:5432/tabularmetadata</Endpoint>
         </Interface>
         <AccessData>
            <Username>luigi</Username>
            <Password>2cf1YRdE5TeiuhQpZUuAOw==</Password>
         </AccessData>
         <Properties>
            <Property>
               <Name>eclipselink.target-database</Name>
               <Value encrypted="false">org.eclipse.persistence.platform.database.PostgreSQLPlatform</Value>
            </Property>
            <Property>
               <Name>driver</Name>
               <Value encrypted="false">org.postgresql.Driver</Value>
            </Property>
         </Properties>
      </AccessPoint>
   </Profile>
</Resource>

Client library

A client library that allows retrieval of database resources represented with the aforementioned model can be found on maven nexus repository:

<dependency>
  <groupId>org.gcube.common</groupId>
  <artifactId>database-resource</artifactId>
  <version>LATEST</version>
</dependency>

In order to obtain database properties a client must first obtain an implementation for DatabaseProvider. The maven artifact comes with a default implementation that leverages Information System services.

Injection can be done in two ways: By directly allocating a ISDatabaseProvider:

DatabaseProvider isDBProvider = new ISDatabaseProvider();

Since the library is CDI enable you can also leverage automatic injection (ISDatabaseProvider is the default implementation):

public class CDIExample {
 
	@Inject
	private DatabaseProvider isDBProvider;
 
        public void test(){
           //isDBProvider is already instantiated
        }
 
}

Before calling methods of ISDatabaseProvider make sure that the scope is set.

private DatabaseProvider isDBProvider = new ISDatabaseProvider();
 
	public void example(){
		ScopeProvider.instance.set("/gcube/devsec");
 
		DatabaseEndpoint endpoint = isDBProvider.get("TabularData Database", "Data-Admin");
 
		DatabaseInstance db = isDBProvider.get("TabularData Database");
 
		String connectionString = isDBProvider.get("TabularData Database", "Data-Admin").getConnectionString();
	}

DatabaseInstance represents the database engine instance itself. From that bean you can access all of the properties like Platform,Hosting node, list of endpoints.

DatabaseEndpoint represents a single database endpoint. From that bean you can access the endpoint connection string, account credentials, generic endpoint properties.