View source for Legacy ISO Metadata Publishing

[[Category:Developer's Guide]][[Category: gCube Spatial Data Infrastructure]]

This page aims to explain how to publish ISO metadata using legacy GIS library ''org.gcube.common.geoserverinterface'' (referred as '''GeoServerInterface''' from now on).

Since various components still rely on ''GeoServerInterface'' to publish geo-referenced data, the library has been enhanced to facilitate publication of ISO Metadata correctly filled (see [[GCube Object Metadata]]).

This guide require the reader to already know the functionality of ''GeoServerInterface'' library.

=Maven Dependency=
The ''GeoServerInterface'' library is released as a maven artifact with the following coordinates

<source lang="xml">
<groupId>org.gcube.common</groupId>
<artifactId>geoserverinterface</artifactId>
</source>

Please note that ISO Metadata facilities are released from version 1.10.2.

===ISO 19115:2003 metadata compliance===
Metadata objects used by the libraries implement [http://www.geoapi.org/ GeoAPI] interfaces, which are fully compliant to [[ISO 19115:2003/19139]]. Current implementation is based on [http://www.geotoolkit.org/modules/metadata/index.html GeoToolkit Metadata] module.

=Code Adaptation=
Introduced enhancements have been designed in order to make code adaptation as easy as possible from developers view.
The class '''org.gcube.common.geoserverinterface.GeoCaller''' remains the main entry point of ''GeoServerInterface'' library for publishing means.

Preexistent publishing methods have been doubled in a way that users just need to change the passed arguments in order to change ISO Metadata publishing behavior.

The following is the list of newly introduced methods

<source lang="java">
public boolean addGeoLayer(String fileUrl, String layerName, String layerTitle, String workspace, GeonetworkCategory category, Metadata toPublishMeta, String scope, String defaultStyle) throws Exception;
public boolean addFeatureType(FeatureTypeRest featureTypeRest,String defaultStyle, GeonetworkCategory category, Metadata toPublishMeta) throws Exception;
public boolean addGeoTiff(String geoTiffUrl, final String layerName, String layerTitle, final String workspace, GeonetworkCategory category, Metadata toPublishMeta, String scope, String defaultStyle) throws Exception;
public boolean addPreExistentGeoTiff(String fileName, final String layerName, String layerTitle, final String workspace, GeonetworkCategory category, Metadata toPublishMeta,String defaultStyle) throws Exception;
</source>

To summerize difference in methods signature :

* removed argument String description
* removed argument String abstract
* added argument org.opengis.metadata.Metadata toPublishMeta : ISO Metadata object representation. It must be already filled with all needed information but layer OGC links, which will be generated at publishing time by the library.
* added arguemnt String defaultStyle : the defaultStyle to be used when generating OGC links in ISO metadata

Instances of ''org.opengis.metadata.Metadata'' interface can be arbitrarily generated  by the invoking application. However, the library has been provided with facilities to easily generate Metadata instances for most gCube applications needs.

=Metadata generation facilities=
Instances of ''org.opengis.metadata.Metadata'' interface can be generated in very different ways. However, we identified a common set of information which every application should include in its published metadata. Providing a common way to generate these metadata entry aims to :

* Reduce the needed effort to generate metadata from the developer's point of view;
* Reuse of code;
* Common behavior to gather common information (see [[#Infrastructure configuration]]);
* Check project's constraints (see [[GCube Object Metadata]]).

==GcubeISOMetadata class==
The utility class ''org.gcube.common.geoserverinterface.bean.iso.GcubeISOMetadata'' lets developers to simply specify the metadata information strictly needed for the generation, relying on internal logic for generic behavior.
===Instantiating===
A GcubeISOMetadata instance should be generated for each publishing request, but this behavior depends on the caller application logic.
At construction time, common information fetched from the gCube IS is loaded. Queries to IS are done via the [[ic-client]], so be sure that a proper scope is setted via ''org.gcube.common.scope.api.ScopeProvider''. 
Loaded configuration is represented by instances of the class ''org.gcube.common.geoserverinterface.bean.iso.EnvironmentConfiguration'' see [[#EnvironmentConfiguration class]].
<source lang="java">

import org.gcube.common.geoserverinterface.bean.iso.EnvironmentConfiguration;
import org.gcube.common.geoserverinterface.bean.iso.GcubeISOMetadata;
import org.gcube.common.scope.api.ScopeProvider;
....
ScopeProvider.instance.set(...);
GcubeISOMetadata meta=new GcubeISOMetadata();
EnvironmentConfiguration configuration = meta.getConfig();
System.out.println("Current configuration is "+configuration);
</source>

===Filling parameters===

The GcubeISOMetadata class exposes setter/add methods to let users specify metadata information. The following is a list of attributes that can be set along with their cardinality. Attributes which cardinality can be more then 1 are setted via the related ''addXXX()'' method, while ''setXXX()'' methods are provided for the other ones.

{|border="1" cellpadding="5" cellspacing="0"
!Attribute Name 
!Type 
!Cardinality
|-
|User 
|java.lang.String
| 1 


|-
|Title
|java.lang.String
|1

|-
|Date
|java.lang.Date
|1

|-
|Presentation Form
|org.opengis.metadata.citation.PresentationForm
|1

|-
|Abstract
|java.lang.String
|1

|-
|Purpose
|java.lang.String
|1

|-
|Credits
|java.lang.String
|1..N

|-
|Descriptive Keyword
|java.lang.String
|1..N

|-
|Topic Category
|org.opengis.metadata.identification.TopicCategory
|1..N

|-
|Extent
|org.geotoolkit.metadata.iso.extent.DefaultExtent
|1

|-
|Geometric Object Type
|org.opengis.metadata.spatial.GeometricObjectType
|1

|-
|Geometry Count
|int
|1

|-
|Topology Level
|org.opengis.metadata.spatial.TopologyLevel
|1

|-
|Resolution
|double
|1

|-
|Graphic Overview
|String
|0..N
|}

The following snippets shows how this parameters are set :

<source lang="java">
import org.gcube.common.geoserverinterface.bean.iso.EnvironmentConfiguration;
import org.gcube.common.geoserverinterface.bean.iso.GcubeISOMetadata;
import org.gcube.common.geoserverinterface.bean.iso.Thesaurus;
import org.geotoolkit.metadata.iso.extent.DefaultExtent;
import org.opengis.metadata.citation.PresentationForm;
import org.opengis.metadata.identification.TopicCategory;
import org.opengis.metadata.spatial.GeometricObjectType;
import org.opengis.metadata.spatial.TopologyLevel;

...

GcubeISOMetadata meta=new GcubeISOMetadata();
//Setter methods
meta.setAbstractField(...);
meta.setCreationDate(...);
meta.setExtent(DefaultExtent.WORLD);
meta.setGeometricObjectType(GeometricObjectType.SURFACE);
meta.setPresentationForm(PresentationForm.MAP_DIGITAL);
meta.setPurpose(...);
meta.setResolution(...);
meta.setTitle(..);
meta.setTopologyLevel(TopologyLevel.GEOMETRY_ONLY);
meta.setUser(...);						

//Add methods
meta.addCredits(..);
meta.addGraphicOverview(...);

//Need to get keywords referred Thesaurus
Thesaurus generalThesaurus=meta.getConfig().getThesauri().get(...);		
meta.addKeyword(..., generalThesaurus);
meta.addKeyword(..., generalThesaurus);


meta.addTopicCategory(TopicCategory.BIOTA);
</source>
===Getting the metadata===
Once the metadata information have been set to the GCubeISOMetadata instance, the caller can obtain the metadata to publish just by calling its '''public org.opengis.metadata.Metadata getMetadata()''' method. In case any mandatory value is missing a ''MissingInformationException'' is thrown.

<source lang="java">
ScopeProvider.instance.set("/gcube/devsec");
GcubeISOMetadata meta=new GcubeISOMetadata();

// Set information
....

// Print out the metadata
XML.marshal(meta.getMetadata(),System.out);

</source>

==Extending default behaviour==
''GCubeISOMetadata'' class can be extended in order to enhance its purpose and behaviour. 
In the following example we define our ''MyApplicationIsoMetadata'' class in order to :

* Automatically set application default values when instatiating;
* Add new mandatory fields to generate data quality information to our metadata, via :
** Adding new member to our class
** Override of protected method '''checkConstraints'''
** Override of public method '''getMetadata()'''


<source lang="java">

import org.gcube.common.geoserverinterface.bean.iso.GcubeISOMetadata;
import org.gcube.common.geoserverinterface.bean.iso.MissingInformationException;
import org.opengis.metadata.Metadata;

//Extends org.gcube.common.geoserverinterface.bean.iso.GcubeISOMetadata
public class MyApplicationIsoMetadata extends GcubeISOMetadata {
	
	//We want this citation to be automatically added to credits
	private static final String applicationCitation="....";

	
	//Our mandatory field
	private String mandatoryField=null;
	
	public MyApplicationIsoMetadata() throws Exception {
		//Let the super class initialize itself
		super();
		//Let's add our citation to credits
		this.getCredits().add(applicationCitation);
	}
	
	@Override
	protected void checkConstraints() throws MissingInformationException {
		// We let the super class to perform its checks before continuing
		super.checkConstraints();
		// Custom check against mandatoryField
		if(mandatoryField==null) throw new MissingInformationException();
	}
		
	@Override
	public Metadata getMetadata() throws URISyntaxException,MissingInformationException {
		Metadata toReturn=super.getMetadata();
		//We set our mandatory field to the metadata
                ........
		return toReturn;
	}

	public String getMandatoryField() {
		return mandatoryField;
	}

	public void setMandatoryField(String mandatoryField) {
		this.mandatoryField = mandatoryField;
	}
}
</source>
=Infrastructure configuration=
Common metadata values (i.e. project citation, project name etc.) are loaded from a gCube generic resource that must be accessible in the current scope.
The given generic resource's body must contain an XML Serialization of [[#EnvironmentConfiguration class]].

==Configuring IS interaction==
The gcube generic resource is found submitting a query to the [[ic-client]] with the following parameters.

*Secondary Type [default value = '''ISO''']
*Resource Name [default value = '''MetadataConstants''']

The Generic resource is cached to avoid overhead in querying the IS. 
The cache TTL, along with the query parameters value can be configured by editing the [[#Properties file]].

==EnvironmentConfiguration class==
The class ''org.gcube.common.geoserverinterface.bean.iso.EnvironmentConfiguration'' represents the metadata constants declared for the entire project.
===Parameters===
{|border="1" cellpadding="5" cellspacing="0"
!Property
!Type
!Cardinality

|-
|colspan="3" bgcolor=lightgrey |'''Protocol declarations'''
|-
|WMS protocol||java.lang.String||0..1
|-
|WFS protocol||java.lang.String||0..1
|-
|WCS protocol||java.lang.String||0..1
|-
|HTTP protocol||java.lang.String||0..1

|-
|colspan="3" bgcolor=lightgrey |'''Project citation'''
|-
|Project Name||java.lang.String||0..1
|-
|Project Citation||java.lang.String||0..1


|-
|colspan="3" bgcolor=lightgrey |'''Distributor Role'''
|-
|Distributor individual name||java.lang.String||0..1
|-
|Distributor e-mail||java.lang.String||0..1
|-
|Distributor organization name||java.lang.String||0..1
|-
|Distributor web site||java.lang.String||0..1


|-
|colspan="3" bgcolor=lightgrey |'''Provider Role'''
|-
|Provider individual name||java.lang.String||0..1
|-
|Provider e-mail||java.lang.String||0..1
|-
|Provider organization name||java.lang.String||0..1
|-
|Provider web site||java.lang.String||0..1

|-
|colspan="3" bgcolor=lightgrey |'''License'''
|-
|License||java.lang.String||0..1

|-
|colspan="3" bgcolor=lightgrey |'''Thesauri Map'''
|-
|Theaurus||org.gcube.common.geoserverinterface.bean.iso.Thesaurus||0..N
|}
===Thesaurus class===
''Thesaurus'' class represents a thesaurus declaration for a given keyword set in ISO metadata (see [[ISO 19115:2003/19139]]).

The following is the list of its members.
{|border="1" cellpadding="5" cellspacing="0"
!Property
!Type
!Cardinality

|-
|Type||org.opengis.metadata.identification.KeywordType||1
|-
|Title||java.lang.String||1
|-
|Citation date||java.util.Date||1
|-
|Citation description||java.lang.String||0..1
|-
|Citation uri||java.lang.String||0..1
|-
|Citation organization||java.lang.String||0..1
|-
|Authored || boolean||1

|}
==Publishing Configuration==
''GeoServerInterface'' library allows administrator to easily configure their environment constants. The following snippets shows how :
<source lang="java">
import org.gcube.common.geoserverinterface.bean.iso.EnvironmentConfiguration;
import org.gcube.common.scope.api.ScopeProvider;
import org.gcube.common.resources.gcore.GenericResource;
....
//Create the configuration
EnvironmentConfiguration config=new EnvironmentConfiguration();
//Set all the values in the configuration
...
//We set the scope where to Publish the configuration
ScopeProvider.instance.set(...);
//Let's actually publish the configuration
GenericResource res=config.publish();
//Just some output log here
String id=res.id();
System.out.println("Published configuration [res ID = "+id+"] under scope "+ScopeProvider.instance.get());
</source>

The method ''config.publish()'' creates and publishes a generic resource with the configured name and secondary type (see [[#Properties file]]).

=Properties file=
Configuration of ''GeoServerInterface'' library's behaviour can be done by editing the ''geoserverInterface.properties'' file distributed inside the library.

The following parameters affects ISO Metadata logic behaviour:

{|border="1" cellpadding="5" cellspacing="0"
!Name
!Expected Type
!Description
!Default

|-
|colspan="3" bgcolor=lightgrey |'''Metadata Publishing'''
|-
|geonetworkGroupId||Integer||Geonetwork groupId to which metadata needs to be published||2
|-
|colspan="3" bgcolor=lightgrey |'''Information System Interaction'''
|-
|genericResourceSecondaryType||String||Generic resource secondary type, used when publishing/loading the project constants (see [[#EnvironmentConfiguration class]])||ISO
|-
|genericResourceName||String||Generic resource name, used when publishing/loading the project constants (see [[#EnvironmentConfiguration class]])||MetadataConstants
|-
|metadataConfigurationTimeToLive||Long||TTL of cached Generic resource. Set to -1 to disable cacheing (see [[#EnvironmentConfiguration class]])||120000

|}