View source for Database resource

[[Category: Developer's Guide]]
= 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:

<source lang="xml">

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

</source>

= Client library =
A client library that allows retrieval of database resources represented with the aforementioned model can be found on [http://maven.research-infrastructures.eu/nexus/index.html#nexus-search;quick~database-resource maven nexus repository]:
<source lang="xml">
<dependency>
  <groupId>org.gcube.common</groupId>
  <artifactId>database-resource</artifactId>
  <version>LATEST</version>
</dependency>
</source>

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:
<source lang="java5">
DatabaseProvider isDBProvider = new ISDatabaseProvider();
</source>

Since the library is CDI enable you can also leverage automatic injection (ISDatabaseProvider is the default implementation):
<source lang="java5">
public class CDIExample {

	@Inject
	private DatabaseProvider isDBProvider;

        public void test(){
           //isDBProvider is already instantiated
        }

}
</source>

Before calling methods of ISDatabaseProvider make sure that the scope is set.
<source lang="java5">
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();
	}
</source>
''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.