6. CRS Management

6.1. Introduction

SECORE (Semantic Coordinate Reference System Resolver) is a server which resolves CRS URLs into full CRS definitions represented in GML 3.2.1. The implementation constitutes the official resolver of OGC, accessible under http://www.opengis.net/def/crs/

SECORE accepts axis, CRS, and CRS template identifiers as input URLs in GET-KVP and RESTful syntax. Further, it accepts general XQuery requests on its CRS database. It is accessible at the following service endpoint:

  • http://www.opengis.net/def/axis for Axis Identifier URLs

  • http://www.opengis.net/def/crs for CRS Identifier URLs and CRS Template URLs

  • http://www.opengis.net/def/crs-compound for Compound CRS URLs

  • http://www.opengis.net/def/equal for semantic CRS URL comparison

  • http://www.opengis.net/def/crs-query for general XQuery requests

If deployed locally, then substitute the official opengis.net part with localhost, or your own domain.

6.2. Service

SECORE stores and queries XML data in a BaseX XML database. On the disk this database is stored in $CATALINA_HOME/webapps/secoredb, this is the directory where the Tomcat process will typically have write access. The database is created and maintained automatically, so no action by the user is required regarding this.

There are two types of definition collections:

  • gml collection which is fixed and cannot be modified; this is based on the EPSG dictionary.

Note

SECORE (def.war) is bundled with several EPSG dataset version, however they may get outdated. For this reason it is possible to manually download the latest EPSG dataset and add it to SECORE as follows:

1. Create a new directory in the secoredb directory (usually in the same directory as def.war, e.g. /var/lib/tomcat/webapps/secoredb) named gml_number.number(.number)?). 2. Extract the EPSG GML dictionary in this folder. 3. Restart Tomcat to allow SECORE to load the new EPSG version.

For example, for EPSG version 9.5.2 it’s necessary to create directory secoredb/gml_9.5.2 and put the extracted GmlDictionary.xml file into it.

  • user collection where users can add/update/delete definitions.

Each definition has an identifier which is checked when updating/deleting a particular definition. When inserting a definition, its identifier must not exist in SECORE already.

<gml:identifier codeSpace="EPSG">
  http://www.opengis.net/def/crs/EPSG/0/4326
</gml:identifier>

Note

Until v9.7, version 0 in CRS identifiers referred to EPSG dataset version 8.5. From v9.7, version 0 in CRS identifiers refers to the latest EPSG dataset version. This means that the CRS definition corresponding to a URL such as http://localhost:8080/def/crs/EPSG/0/4326 is dynamic and may change with new releases of the EPSG dataset. For this reason it is now recommended to specify an exact version, e.g. 9.4.2 instead of 0.

6.2.1. User interface

The SECORE database tree can be viewed and (upon login) modified via graphical web interface at http://your.server/def/index.jsp.

More generally, any folder and definition can turn to EDIT mode by appending a /browse.jsp to its URI; e.g.

  • http://your.server/def/uom/EPSG/0/9001/browse.jsp will let you view/edit EPSG:9001 unit of measure, whereas

  • "http://your.server/def/uom/EPSG/0/browse.jsp" will let you either remove EPSG UoM definitions or add a new one, not necessarily under the EPSG branch: the "gml:identifier" of the new definition will determine its position in the tree.

In this document you can find hints on how to to define new GML definitions of CRSs. Mind that compounding is achieved at resolve-time by querying SECORE with a "crs-compound" path, so that only single CRS definitions should be added.

With regard to parametrized CRSs, you should mind that relative XPaths are not allowed (either start with / or // when selecting nodes); non-numeric parameters must be embraced by single or double quotes both when setting optional default values in the definition or when setting custom values in the URI.

6.2.2. Configuration

The SECORE can be configured via changing settings in /opt/rasdaman/etc/secore.properties. For changes to take effect, system Tomcat (if SECORE def.jar is embedded in rasdaman.war or def.war is deployed as a standalone web application) or SECORE with embedded Tomcat (if SECORE is started with java -jar def.war) needs to be restarted after editing this file.

6.2.2.1. General

  • db_updates.path set the directory holding CRS definition updates (insert, delete) to apply to userdb.

    • Default: /opt/rasdaman/share/rasdaman/secore/

    • Need to change: NO

  • service.url set the service URL, used in automatic substitution of URNs (urn:ogc:def) and URLs (e.g. http://localhost:8080/def). Set this parameter to your public service URL if SECORE is behind a proxy. Note: used only when running SECORE as a standalone web application (def.war is started with external / embedded Tomcat). When embedded in petascope as def.jar, this setting is dictated by petascope_servlet_url property in petascope.properties file. e.g. petascope_servlet_url=http://your_domain.com/rasdaman/ows then SECORE will show URLs in GML text from the resolved request as http://your_domain.com/rasdaman/def

    • Default: http://localhost:8080/def

    • Need to change: NO

  • codespace set the default codeSpace to be used for definitions constructed on the fly by crs-compound. The value of the codeSpace attribute (if present) shall indicate a dictionary, thesaurus, classification scheme, authority, or pattern for the term.

    • Default: codespace=OGC

    • Need to change: NO

  • server.contextPath when SECORE (def.war) is running in embedded Tomcat, this setting allows to control the prefix in the web application URL, i.e. the name /def in http://localhost:8080/def.

    • Default: /def

    • Need to change: NO

  • max_cache_size set the maximum amount of memory (in bytes) to use for caching successful requests; set to 0 to avoid cache. It is recommended to consider increasing the parameter if the system has more RAM, but make sure to correspondingly update the -Xmx option for Tomcat as well.

    • Default: 100000000f (100 MB)

    • Need to change: NO

6.2.2.2. Deployment

  • server.port set the port on which SECORE will listen when starting SECORE manually in embedded Tomcat with java -jar def.war. It has no effect when SECORE is deployed in external Tomcat or embedded inside rasdaman.war as a dependency file as def.jar.

    • Default: 8080

    • Need to change: YES when port 8080 is occupied by another process, e.g. external Tomcat

  • secoredb.path set the path to folder where SECORE with embedded Tomcat or SECORE as a dependency-of-petascope stores its database. This folder needs read and write permissions for the system user running SECORE. Note: It has no effect when SECORE (def.war) is deployed in an external Tomcat, then a secoredb folder will be automatically created in Tomcat’s webapps directory for this purpose.

    • Default: /opt/rasdaman/data/secore

    • Need to change: NO

6.2.2.3. Security

  • secore_admin_user set the username with read/write access to various service management capabilities (e.g. adding / deleting CRS,…); login at http://localhost:8080/def/index.jsp.

    • Default: secoreuser

    • Need to change: NO

  • secore_admin_pass set the password for the user set for secore_admin_user. It is recommended to change the default password.

    • Default: secorepasswd

    • Need to change: YES (recommended)

  • ignore_agents_matching set the list of user-agent names in the HTTP header sending the requests to SECORE which should not be processed; SECORE returns empty content with HTTP code 200 when user-agent containing one of the name from the list. Used in the case when bots from google or facebook crawling public SECORE with many invalid requests and degrade SECORE’s performance greatly.

    • Default:

    • Need to change: NO

6.2.2.4. Logging

rasdaman-geo uses the log4j library version 2.17.2 provided by Spring Boot to log information/errors in a secore.log file. See the log4j document for more details.

  • Configuration for SECORE logging; by default only level INFO or higher is logged to a file. The valid logging levels are TRACE, DEBUG, INFO, WARN, ERROR and FATAL.

    log4j.rootLogger=INFO, rollingFile

  • Configure file logging. The paths for file logging specified below should be write-accessible by the system user running Tomcat. If running embedded Tomcat, then the files should be write accessible by the system user running rasdaman, which is normally rasdaman.

    log4j.appender.rollingFile.layout=org.apache.log4j.PatternLayout
log4j.appender.rollingFile.layout.ConversionPattern=%6p [%d{yyyy-MM-dd HH:mm:ss}] %c{1}@%L: %m%n

  • Select one strategy for rolling files and comment out the other. Default is rolling files by time interval.

    # 1. Rolling files by maximum size and index
#log4j.appender.rollingFile.File=@LOG_DIR@/secore.log
#log4j.appender.rollingFile.MaxFileSize=10MB
#log4j.appender.rollingFile.MaxBackupIndex=10
#log4j.appender.rollingFile=org.apache.log4j.RollingFileAppender

# 2. Rolling files by time interval (e.g. once a day, or once a month)
log4j.appender.rollingFile.rollingPolicy.ActiveFileName=@LOG_DIR@/secore.log
log4j.appender.rollingFile.rollingPolicy.FileNamePattern=@LOG_DIR@/secore.%d{yyyyMMdd}.log.gz
log4j.appender.rollingFile=org.apache.log4j.rolling.RollingFileAppender
log4j.appender.rollingFile.rollingPolicy=org.apache.log4j.rolling.TimeBasedRollingPolicy

6.2.2.5. Security

You should set the secore_admin_user, secore_admin_pass options to prevent unauthorized users from editing CRS definitions in the userdb CRS collection. If these are not set or commented out, then the admin pages have public access.

6.2.2.6. Standalone deployment

Instead of running SECORE as part of petascope (rasdaman.war) by default, you can run def.war as a standalone web application through its embedded Tomcat (see port confiugration) or deployed in an external Tomcat.

In this case SECORE can be accessed at http://localhost:8082/def (if SECORE is running with embedded Tomcat and server.port=8082 has been set) or http://localhost:8080/def (if external Tomcat is running at port 8080).

6.2.2.7. Logging

At the end of secore.properties you will find the logging configuration. It is recommended to adjust this, and make sure that Tomcat has permissions to write the secore.log file.

6.3. Concepts

6.3.1. CRS templates

CRS templates are concrete definitions targeted by parameterized CRSs where one or more named parameters allow the customization of one or more elements in the template itself. As such, they describe (possibly infinite) sets of concrete CRSs.

Note

The term “parametrized” is generally avoided because it may lead to confusion with the term “parametric” in OGC Abstract Topic 2 / ISO 19111-2:2009 which has a significantly different meaning.

Parameters can be resolved through values provided in the CRS URI, or through defaults defined in the CRS Template definition. Additionally, expressions (“formulae”) can be associated with a CRS Template which evaluate to values when instantiated with parameter values. All values, whether instantiated in a URL request or coming from a default or a formula, can be substituted in one or several places in the concrete CRS definition associated with the CRS Template.

Example

The following URI defines the Auto Orthographic CRS 42003 specified in sub clauses 6.7.3.4 and B.9 of WMS 1.3.0 for “meter” as unit of measure and centred at 100? West longitude and 45? North latitude:

http://www.opengis.net/def/crs?
  authority=OGC&
  version=1.3&
  code=AUTO42003&
  UoM=m&
  CenterLongitude=-100&
  CenterLatitude=45&

Note

Additional examples of not-completely-specified objects can be found in sub clauses B.7, B.8, B.10, and B.11 of the`WMS 1.3.0 spec <http://portal.opengeospatial.org/files/?artifact_id=14416>`__, and in sub clauses 10.1 through 10.3 of OGC 05-096r1 (GML 3.1.1 grid CRSs profile).

6.3.1.1. Structure

Formally, a CRS Template is a GML document with root crsnts:AbstractCRSTemplate. It contains an element crsnts:CrsDefinition of some instantiatable subtype of gml:AbstractCRS together with a list of formal parameters.

Parameters are crsnts:Parameter elements listed in the crsnts:Parameters section. A formal parameter consists of a locally unique name, an XPath target expression indicating one or a set of substitution points relative to the CRS subnode, optionally a default value, and optionally a formula. Further, each parameter has a type associated.

The crsnts:value element contains a well-formed formula adhering to the JSR scripting syntax as specified in JSR-233 [5]. The type associated in the formula’s crsnts:Parameters element denotes the result type of the expression. Names are enclosed in ${ and }; when used in a formula they shall contain only references to parameter names defined in the same CRS Template, and no (direct or indirect) recursive references across formulae.

Note

In particular, a formula cannot have its own parameter name as a free parameter. The target expression in crsnts:target indicates the places where, during request evaluation, the resulting parameter (obtained from URL input, or formula evaluation, or by using the default) gets applied to the CRS definition, assuming crsnts:CrsDefinition as the relative document root for XPath evaluation.

Example

The following XML snippet defines a geodetic Parametrized CRS with formal parameter x substituting parameter values in all (fictitious) axisName elements appearing the GeodeticCRS root of the CRS definition:

<crsnts:ParameterizedCRS>
  <gml:identifier>...</gml:identifier>
  <gml:scope>...</gml:scope>
  <crsnts:parameters>
    <crsnts:parameter name="lon" >
      <crsnts:value>90</crsnts:value>
      <crsnts:target>//longitude | //Longitude</crsnts:target>
    </crsnts:parameter>
    <crsnts:parameter name="zone">
      <crsnts:target>//greenwichLongitude</crsnts:target>
      <crsnts:value>
        min(floor((${lon} + 180.0) / 6.0) + 1,60)
      </crsnts:value>
    </crsnts:parameter>
  </crsnts:parameters>
  <crsnts:targetReferenceSystem
    xlink:href="http://www.opengis.net/def/crs/EPSG/0/4326"/>
</crsnts:ParameterizedCRS>

6.3.1.2. Resolution

The result of a URI request against a Parametrized CRS depends on the degree of parameter matching; it is GML document with its root being an instantiatable subtype of either gml:AbstractCRS or crsnts:AbstractCRSTemplate. The response is:

  • In case all formal parameters in the Parametrized CRS addressed are matched: a CRS definition where all parameters matched are resolved.

    Example. Assuming that the name of the above Parametrized CRS example is my-own-crs, a possible instantiation of this CRS to a concrete CRS Identifier is

    http://www.opengis.net/def/crs/my-own-crs?lon=47.6

    The response to this instantiation is

    <gml:GeodeticCRS>
  ...
<gml:GeodeticCRS>

  • In case not all parameters are matched: a Parametrized CRS where all parameters matched are resolved, their corresponding crsnts:Parameter is removed, and only the non-matched parameters remain in the template.

    Example. Assuming the same example as above, the CRS itself can be obtained through

    http://www.opengis.net/def/crs/my-own-crs

    The response to this request is

    <crsnts:ParameterizedCRS>
  <gml:identifier>...</gml:identifier>
  <gml:scope>...</gml:scope>
  <crsnts:parameters>
    ...
  </crsnts:parameters>
  <crsnts:targetReferenceSystem xlink:href="..."/>
</crsnts:ParameterizedCRS>

6.3.2. CRS equality

It is possible that one and the same CRS, axis, etc. is identified by a number of syntactically different URLs, and it is not straightforward for applications to decide about equivalence of two given URIs. To remedy this, a comparison predicate is available in SECORE. A request sent to URL

http://www.opengis.net/def/crs-equal?1=A&2=B

containing two URLs A and B listed as GET/KVP parameters with names 1 and 2, respectively, will result in a response of true if and only if both URLs identify the same concept, and false otherwise; the response is embedded in an XML document.

Example

Comparing EPSG codes 4327 and 4326 can be done with this URL:

http://www.opengis.net/def/equal?
  1=http://www.opengis.net/def/crs/EPSG/0/4327
 &2=http://www.opengis.net/def/crs/EPSG/0/4326

The response will look like this:

<crsnts:comparisonResult xmlns='http://www.opengis.net/crs-nts/1.0'>
  <crsnts:equal>false</crsnts:equal>
  <crsnts:reason>
    <![CDATA[ ...description text... ]]>
  </crsnts:reason>
</crsnts:comparisonResult>

6.3.3. Directly Querying SECORE

An XQuery GET or POST request sent to URL http://www.opengis.net/def/crs-query will result in a document obtained from evaluating the XQuery request according to the XQuery standard.