CADC-12390 updated README for new properties file format

caom2-repo-server/README.md

@@ -1,49 +1,144 @@
+# OpenCADC CAOM repository server library
 
-The CaomRepoConfig.properties file provides a simple example that could be used for testing. For real deployment, this library will look for a file named <service name>.properties in ${user.home}/config of the user running the application server (e.g. tomcat). The <service name> is the first path element in URLs and typically matches the name of the deployed war file. For example, The CADC deploys this service as caom2repo.war so the config file is called ${user.home}/config/caom2repo.properties. Note that this config file is read from the filesystem for each request so changes are "immediately live".
+### caom2-repo-server configuration file
 
-The CaomRepoConfig.properties file uses the following format:
+When deployed as a web service, the library looks for a configuration file called `${user.home}/config/<service name>.properties`.
+For example, if the service was deployed as caom2repo.war, it would look for a configuration file called `${user.home}/config/caom2repo.properties`.
+Note that this config file is read from the filesystem for each request so changes are "immediately live".
+
+Each entry in the properties file configures a collection. 
+Each entry has a name, followed by entry-specific properties.
 
 ```
-collection = <datasource name> <database> <schema> <obs table> <read-only group> <read-write group> <SQL generator class> basePublisherID=<ivo uri> [<key1=value1 key2=value2 ...>]
+# required properties
+org.opencadc.caom2.repo.entry = {entry name}
+{entry name}.collection = {collection name}
+{entry name}.datasource = {datasource name}
+{entry name}.database = {database}
+{entry name}.schema = {schema}
+{entry name}.obsTable = {Observation table}
+{entry name}.sqlGenerator = {SQL generator class}
+{entry name}.basePublisherID = {URI}
+
+# optional properties
+{entry name}.readOnlyGroup = {group URI}
+{entry name}.readWriteGroup = {group URI}
+{entry name}.operatorGroup = {group URI}
+{entry name}.staffGroup = {group URI}
+{entry name}.proposalGroup = {true|false}
+{entry name}.computeMetadata = {true|false}
 ```
 
-Each entry in the properties file configures a collection. Except for basePublisherID (mandatory), key=value pairs are optional. The computeMetadata option enables computation and persistence of <<computed>> metadata (generally, Plane metadata aggregated from the artifacts). The computeMetadataValidation options enables extra validation by performing the metadata computations, but the values are not persisted.
+_org.opencadc.caom2.repo.entry_ creates a new rule with the specified entry name.
+
+_{entry name}.datasource_ is the JNDI datasource name for the entry specified in the service deployment descriptor.
+
+_{entry name}.database_ is the CAOM database name for the entry.
+
+_{entry name}.schema_ is the CAOM schema name for the entry.
+
+_{entry name}.obsTable_ is the CAOM Observation table name.
+
+_{entry name}.sqlGenerator_ is a plugin implementation to support the database. There is currently only one 
+implementation that is tested with PostgeSQL (10+), ca.nrc.cadc.caom2.persistence.PostgreSQLGenerator. 
+Making this work with other database servers in future may require a different implementation.
+
+_{entry name}.bashPublisherID_  is the base for generating Plane publisherID values. 
+The base is an uri of the form `ivo://<authority>[/<path>]`
+publisherID values: `<basePublisherID>/<collection>?<observationID>/<productID>`
+
+_{entry name}.readOnlyGroup_ specifies a group (one per line) that can read (get) matching assets (default: empty list).
 
+_{entry name}.readWriteGroup_ entry specifies a group (one per line) that can read and write (get/put/update/delete) 
+matching assets (default: empty list).
 
-**How to create groups/tuples**
+_{entry name}.operatorGroup_ is an operator group that spans across all collections. (default: no operator group)
 
-In the CaomRepoConfig.properties file, configure each collection with the desired proposal group, operator group and staff group.
+_{entry name}.staffGroup_ is a staff group is associated with a collection, and is added as an admin 
+to the proposal group. Both groups use the same GMS service, with the resourceID of the service 
+coming from the staff group. (default: no staff group)
 
-The proposal group option is a boolean flag which indicates whether a proposal group is to be generated for the collection. When proposalGroup=true is specified, a proposal group with an arbitrary prefix is created, using a GMS service, for the collection. 
+_{entry name}.proposalGroup_ is a boolean flag which indicates whether a proposal group is to be generated 
+for the collection. When proposalGroup=true is specified, a proposal group with an arbitrary prefix is created, 
+using a GMS service, for the collection. (default: false)
 
-An operator group spans across all collections. 
+_{entry name}.computeMetadata_ enables computation and persistence of computed metadata(generally, Plane metadata 
+aggregated from the artifacts). (default: false)
 
-A staff group is associated with a collection, and is added as an admin to the proposal group. Both groups use the same GMS service, with the resourceID of the service coming from the staff group.
 
-**Configuring groups/tuples**
+## How to create groups/tuples
 
-The optional key=value pairs can be used to specify an abitratry operator group, an arbitrary staff group and a flag to enable proposal groups to be checked/created and granted access to observations. If created, proposal groups have URIs of the form 
+In the properties file, configure each collection with the desired proposal group, operator group and staff group.
+
+The proposal group option is a boolean flag which indicates whether a proposal group is to be generated 
+for the collection. When proposalGroup=true is specified, a proposal group with an arbitrary prefix is created, 
+using a GMS service, for the collection.
+
+An operator group spans across all collections.
+
+A staff group is associated with a collection, and is added as an admin to the proposal group. 
+Both groups use the same GMS service, with the resourceID of the service coming from the staff group.
+
+## Configuring groups/tuples
+
+The _operatorGroup_ and _staffGroup_ properties can be used to specify an arbitrary operator group and staff group. 
+The _proposalGroup_ flag enables proposal groups to be checked/created and granted access to observations. 
+If created, proposal groups have URIs of the form:
 
 ```
 <GMS service URI>?<collection>-<Observation.proposal.id>
 ```
 
-Where <GMS service URI> is extracted from the staff group (the satff group isn assigned admin permission on the proposal group so both groups must exist in the same GMS service). For example:
+Where <GMS service URI> is extracted from the staff group (the staff group isn't assigned admin permission 
+on the proposal group so both groups must exist in the same GMS service). For example:
 
 ```
-TEST = jdbc/caom2repo caom2test dbo caom2_Observation ivo://cadc.nrc.ca/gms?caom2TestGroupRead ivo://cadc.nrc.ca/gms?caom2TestGroupWrite ca.nrc.cadc.caom2.repo.PostgreSQLGeneratorImpl basePublisherID=ivo://cadc.nrc.ca proposalGroup=true staffGroup=ivo://cadc.nrc.ca/gms?JCMT-Staff
+org.opencadc.caom2.repo.entry = TEST
+TEST.datasource = jdbc/caom2repo
+TEST.database = caom2test
+TEST.schema = dbo
+TEST.obsTable = caom2_Observation
+TEST.sqlGenerator = ca.nrc.cadc.caom2.repo.PostgreSQLGeneratorImpl
+TEST.basePublisherID = ivo://cadc.nrc.ca
+TEST.readOnlyGroup = ivo://cadc.nrc.ca/gms?caom2TestGroupRead
+TEST.readWriteGroup = ivo://cadc.nrc.ca/gms?caom2TestGroupWrite
+TEST.staffGroup = ivo://cadc.nrc.ca/gms?JCMT-Staff
+TEST.proposalGroup = true
 ```
 
-configures the 'TEST' collection with a staff group and enables proposal group creation.
+configures the `TEST` collection with a staff group and enables proposal group creation.
+
 
 ```
-TEST1 = jdbc/caom2repo caom2test dbo caom2_Observation ivo://cadc.nrc.ca/gms?caom2TestGroupRead ivo://cadc.nrc.ca/gms?caom2TestGroupWrite ca.nrc.cadc.caom2.repo.PostgreSQLGeneratorImpl proposalGroup=false operatorGroup=ivo://cadc.nrc.ca/gms?CADC staffGroup=ivo://cadc.nrc.ca/gms?JCMT-Staff
+org.opencadc.caom2.repo.entry = TEST1
+TEST1.datasource = jdbc/caom2repo
+TEST1.database = caom2test
+TEST1.schema = dbo
+TEST1.obsTable = caom2_Observation
+TEST1.sqlGenerator = ca.nrc.cadc.caom2.repo.PostgreSQLGeneratorImpl
+TEST1.basePublisherID = ivo://cadc.nrc.ca
+TEST1.readOnlyGroup = ivo://cadc.nrc.ca/gms?caom2TestGroupRead
+TEST1.readWriteGroup = ivo://cadc.nrc.ca/gms?caom2TestGroupWrite
+TEST1.operatorGroup = ivo://cadc.nrc.ca/gms?CADC
+TEST1.staffGroup = ivo://cadc.nrc.ca/gms?JCMT-Staff
+TEST1.proposalGroup = false
 ```
 
-configures the 'TEST1' collection with an operator group and a staff group without a proposal group, and is equivalent to:
+configures the `TEST1` collection with an operator group and a staff group without a proposal group, and is equivalent to:
+
 
 ```
-TEST1 = jdbc/caom2repo caom2test dbo caom2_Observation ivo://cadc.nrc.ca/gms?caom2TestGroupRead ivo://cadc.nrc.ca/gms?caom2TestGroupWrite ca.nrc.cadc.caom2.repo.PostgreSQLGeneratorImpl operatorGroup=ivo://cadc.nrc.ca/gms?CADC staffGroup=ivo://cadc.nrc.ca/gms?JCMT-Staff 
+org.opencadc.caom2.repo.entry = TEST1
+TEST1.datasource = jdbc/caom2repo
+TEST1.database = caom2test
+TEST1.schema = dbo
+TEST1.obsTable = caom2_Observation
+TEST1.sqlGenerator = ca.nrc.cadc.caom2.repo.PostgreSQLGeneratorImpl
+TEST1.basePublisherID = ivo://cadc.nrc.ca
+TEST1.readOnlyGroup = ivo://cadc.nrc.ca/gms?caom2TestGroupRead
+TEST1.readWriteGroup = ivo://cadc.nrc.ca/gms?caom2TestGroupWrite
+TEST1.operatorGroup = ivo://cadc.nrc.ca/gms?CADC
+TEST1.staffGroup = ivo://cadc.nrc.ca/gms?JCMT-Staff
 ```
 
-because the default value of 'proposalGroup' is 'false'.
+because the default value of `proposalGroup` is `false`.

caom2-repo-server/src/main/java/ca/nrc/cadc/caom2/repo/AccessQueryRunner.java → caom2-repo-server/src/main/java/org/opencadc/caom2/repo/AccessQueryRunner.java

@@ -65,7 +65,7 @@
 ************************************************************************
 */
 
-package ca.nrc.cadc.caom2.repo;
+package org.opencadc.caom2.repo;
 
 import ca.nrc.cadc.auth.AuthenticationUtil;
 import ca.nrc.cadc.caom2.access.AccessUtil;
@@ -74,8 +74,6 @@
 import ca.nrc.cadc.caom2.xml.ArtifactAccessWriter;
 import ca.nrc.cadc.dali.ParamExtractor;
 import ca.nrc.cadc.net.ResourceNotFoundException;
-import ca.nrc.cadc.reg.Standards;
-import ca.nrc.cadc.reg.client.LocalAuthority;
 import ca.nrc.cadc.rest.SyncOutput;
 import ca.nrc.cadc.uws.Job;
 import ca.nrc.cadc.uws.server.JobRunner;

caom2-repo-server/src/main/java/ca/nrc/cadc/caom2/repo/CaomRepoConfig.java → caom2-repo-server/src/main/java/org/opencadc/caom2/repo/CaomRepoConfig.java

@@ -67,7 +67,7 @@
 ************************************************************************
 */
 
-package ca.nrc.cadc.caom2.repo;
+package org.opencadc.caom2.repo;
 
 import ca.nrc.cadc.caom2.Observation;
 import ca.nrc.cadc.caom2.ac.ReadAccessGenerator;

caom2-repo-server/src/main/java/ca/nrc/cadc/caom2/repo/CheckWcsLib.java → caom2-repo-server/src/main/java/org/opencadc/caom2/repo/CheckWcsLib.java

@@ -67,7 +67,7 @@
 ************************************************************************
 */
 
-package ca.nrc.cadc.caom2.repo;
+package org.opencadc.caom2.repo;
 
 import ca.nrc.cadc.vosi.avail.CheckException;
 import ca.nrc.cadc.vosi.avail.CheckResource;

caom2-repo-server/src/main/java/ca/nrc/cadc/caom2/repo/PropertyAuthorizer.java → caom2-repo-server/src/main/java/org/opencadc/caom2/repo/PropertyAuthorizer.java

@@ -67,7 +67,7 @@
  ************************************************************************
  */
 
-package ca.nrc.cadc.caom2.repo;
+package org.opencadc.caom2.repo;
 
 import ca.nrc.cadc.auth.AuthenticationUtil;
 import ca.nrc.cadc.cred.client.CredUtil;

caom2-repo-server/src/main/java/ca/nrc/cadc/caom2/repo/action/DeleteAction.java → caom2-repo-server/src/main/java/org/opencadc/caom2/repo/action/DeleteAction.java

@@ -67,7 +67,7 @@
 ************************************************************************
 */
 
-package ca.nrc.cadc.caom2.repo.action;
+package org.opencadc.caom2.repo.action;
 
 import ca.nrc.cadc.caom2.ObservationState;
 import ca.nrc.cadc.caom2.ObservationURI;

caom2-repo-server/src/main/java/ca/nrc/cadc/caom2/repo/action/GetAction.java → caom2-repo-server/src/main/java/org/opencadc/caom2/repo/action/GetAction.java

@@ -67,7 +67,7 @@
 ************************************************************************
 */
 
-package ca.nrc.cadc.caom2.repo.action;
+package org.opencadc.caom2.repo.action;
 
 import ca.nrc.cadc.caom2.ObservationResponse;
 import ca.nrc.cadc.caom2.ObservationState;

caom2-repo-server/src/main/java/ca/nrc/cadc/caom2/repo/action/GetAction23.java → caom2-repo-server/src/main/java/org/opencadc/caom2/repo/action/GetAction23.java

@@ -67,7 +67,7 @@
 ************************************************************************
 */
 
-package ca.nrc.cadc.caom2.repo.action;
+package org.opencadc.caom2.repo.action;
 
 import ca.nrc.cadc.caom2.xml.ObservationWriter;
 import ca.nrc.cadc.caom2.xml.XmlConstants;

caom2-repo-server/src/main/java/ca/nrc/cadc/caom2/repo/action/GetDeletedAction.java → caom2-repo-server/src/main/java/org/opencadc/caom2/repo/action/GetDeletedAction.java

@@ -65,7 +65,7 @@
 ************************************************************************
 */
 
-package ca.nrc.cadc.caom2.repo.action;
+package org.opencadc.caom2.repo.action;
 
 import ca.nrc.cadc.caom2.DeletedObservation;
 import ca.nrc.cadc.caom2.persistence.DeletedEntityDAO;

caom2-repo-server/src/main/java/ca/nrc/cadc/caom2/repo/action/GetPermissionsAction.java → caom2-repo-server/src/main/java/org/opencadc/caom2/repo/action/GetPermissionsAction.java

@@ -67,13 +67,13 @@
  ************************************************************************
  */
 
-package ca.nrc.cadc.caom2.repo.action;
+package org.opencadc.caom2.repo.action;
 
 import ca.nrc.cadc.caom2.access.AccessUtil;
 import ca.nrc.cadc.caom2.access.ArtifactAccess;
 import ca.nrc.cadc.caom2.persistence.ReadAccessDAO;
-import ca.nrc.cadc.caom2.repo.CaomRepoConfig;
-import ca.nrc.cadc.caom2.repo.PropertyAuthorizer;
+import org.opencadc.caom2.repo.CaomRepoConfig;
+import org.opencadc.caom2.repo.PropertyAuthorizer;
 import ca.nrc.cadc.io.ByteCountOutputStream;
 import ca.nrc.cadc.net.ResourceNotFoundException;
 import ca.nrc.cadc.rest.InlineContentHandler;

caom2-repo-server/src/main/java/ca/nrc/cadc/caom2/repo/action/ObservationInlineContentHandler.java → caom2-repo-server/src/main/java/org/opencadc/caom2/repo/action/ObservationInlineContentHandler.java

@@ -67,13 +67,12 @@
  ************************************************************************
  */
 
-package ca.nrc.cadc.caom2.repo.action;
+package org.opencadc.caom2.repo.action;
 
 import ca.nrc.cadc.caom2.Observation;
 import ca.nrc.cadc.caom2.xml.ObservationParsingException;
 import ca.nrc.cadc.caom2.xml.ObservationReader;
 import ca.nrc.cadc.io.ByteCountInputStream;
-import ca.nrc.cadc.io.ByteLimitExceededException;
 import ca.nrc.cadc.rest.InlineContentException;
 import ca.nrc.cadc.rest.InlineContentHandler;
 

caom2-repo-server/src/main/java/ca/nrc/cadc/caom2/repo/action/PostAction.java → caom2-repo-server/src/main/java/org/opencadc/caom2/repo/action/PostAction.java

@@ -67,13 +67,12 @@
 ************************************************************************
 */
 
-package ca.nrc.cadc.caom2.repo.action;
+package org.opencadc.caom2.repo.action;
 
 import ca.nrc.cadc.caom2.Observation;
 import ca.nrc.cadc.caom2.ObservationState;
 import ca.nrc.cadc.caom2.ObservationURI;
 import ca.nrc.cadc.caom2.persistence.ObservationDAO;
-import ca.nrc.cadc.net.PreconditionFailedException;
 import ca.nrc.cadc.net.ResourceNotFoundException;
 import ca.nrc.cadc.rest.InlineContentHandler;
 import java.net.URI;

caom2-repo-server/src/main/java/ca/nrc/cadc/caom2/repo/action/PutAction.java → caom2-repo-server/src/main/java/org/opencadc/caom2/repo/action/PutAction.java

@@ -67,7 +67,7 @@
 ************************************************************************
 */
 
-package ca.nrc.cadc.caom2.repo.action;
+package org.opencadc.caom2.repo.action;
 
 import ca.nrc.cadc.caom2.Observation;
 import ca.nrc.cadc.caom2.ObservationState;

caom2-repo-server/src/main/java/ca/nrc/cadc/caom2/repo/action/RepoAction.java → caom2-repo-server/src/main/java/org/opencadc/caom2/repo/action/RepoAction.java

@@ -67,7 +67,7 @@
 ************************************************************************
 */
 
-package ca.nrc.cadc.caom2.repo.action;
+package org.opencadc.caom2.repo.action;
 
 import ca.nrc.cadc.ac.UserNotFoundException;
 import ca.nrc.cadc.ac.client.GMSClient;
@@ -80,7 +80,7 @@
 import ca.nrc.cadc.caom2.compute.ComputeUtil;
 import ca.nrc.cadc.caom2.persistence.DeletedEntityDAO;
 import ca.nrc.cadc.caom2.persistence.ObservationDAO;
-import ca.nrc.cadc.caom2.repo.CaomRepoConfig;
+import org.opencadc.caom2.repo.CaomRepoConfig;
 import ca.nrc.cadc.caom2.util.CaomValidator;
 import ca.nrc.cadc.caom2.xml.ObservationParsingException;
 import ca.nrc.cadc.cred.client.CredUtil;