Author: desruisseaux
Date: Fri Feb 23 15:28:45 2018
New Revision: 1825133

URL: http://svn.apache.org/viewvc?rev=1825133&view=rev
Log:
Add a ParameterDescriptor for "create" parameter.

Modified:
    
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.java
    
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.properties
    
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources_fr.properties
    
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/URIDataStore.java
    
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/folder/FolderStoreProvider.java
    
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java

Modified: 
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.java
URL: 
http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.java?rev=1825133&r1=1825132&r2=1825133&view=diff
==============================================================================
--- 
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.java
 [UTF-8] (original)
+++ 
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.java
 [UTF-8] Fri Feb 23 15:28:45 2018
@@ -132,6 +132,11 @@ public final class Resources extends Ind
         public static final short ConcurrentWrite_1 = 20;
 
         /**
+         * Whether to allow new data store creation if the source to open does 
not already exist.
+         */
+        public static final short DataStoreCreate = 51;
+
+        /**
          * Character encoding used by the data store.
          */
         public static final short DataStoreEncoding = 29;

Modified: 
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.properties
URL: 
http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.properties?rev=1825133&r1=1825132&r2=1825133&view=diff
==============================================================================
--- 
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.properties
 [ISO-8859-1] (original)
+++ 
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources.properties
 [ISO-8859-1] Fri Feb 23 15:28:45 2018
@@ -33,6 +33,7 @@ ClosedReader_1                    = This
 ClosedWriter_1                    = This {0} writer is closed.
 ConcurrentRead_1                  = One or more read operations are in 
progress in the \u201c{0}\u201d data store.
 ConcurrentWrite_1                 = A write operation is in progress in the 
\u201c{0}\u201d data store.
+DataStoreCreate                   = Whether to allow new data store creation 
if the source to open does not already exist.
 DataStoreEncoding                 = Character encoding used by the data store.
 DataStoreLocale                   = Formating conventions of dates and numbers.
 DataStoreLocation                 = Data store location as a file or URL.

Modified: 
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources_fr.properties
URL: 
http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources_fr.properties?rev=1825133&r1=1825132&r2=1825133&view=diff
==============================================================================
--- 
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources_fr.properties
 [ISO-8859-1] (original)
+++ 
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/Resources_fr.properties
 [ISO-8859-1] Fri Feb 23 15:28:45 2018
@@ -38,6 +38,7 @@ ClosedReader_1                    = Ce l
 ClosedWriter_1                    = Cet encodeur {0} est ferm\u00e9.
 ConcurrentRead_1                  = Une ou plusieurs op\u00e9rations de 
lecture sont en cours sur les donn\u00e9es de \u00ab\u202f{0}\u202f\u00bb.
 ConcurrentWrite_1                 = Une op\u00e9ration d\u2019\u00e9criture 
est en cours sur les donn\u00e9es de \u00ab\u202f{0}\u202f\u00bb.
+DataStoreCreate                   = Indique si l\u2019on autorise la 
cr\u00e9ation d\u2019une nouvelle source de donn\u00e9es si la source \u00e0 
ouvrir n\u2019existe pas d\u00e9j\u00e0.
 DataStoreEncoding                 = Encodage des caract\u00e8res utilis\u00e9 
par la source de donn\u00e9es.
 DataStoreLocale                   = Conventions d\u2019\u00e9criture des dates 
et des nombres.
 DataStoreLocation                 = Chemin (fichier ou URL) vers la source de 
donn\u00e9es.

Modified: 
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/URIDataStore.java
URL: 
http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/URIDataStore.java?rev=1825133&r1=1825132&r2=1825133&view=diff
==============================================================================
--- 
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/URIDataStore.java
 [UTF-8] (original)
+++ 
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/URIDataStore.java
 [UTF-8] Fri Feb 23 15:28:45 2018
@@ -97,17 +97,24 @@ public abstract class URIDataStore exten
      *
      * @author  Johann Sorel (Geomatys)
      * @author  Martin Desruisseaux (Geomatys)
-     * @version 0.8
+     * @version 1.0
      * @since   0.8
      * @module
      */
     public abstract static class Provider extends DataStoreProvider {
         /**
-         * Description of the location parameter.
+         * Description of the {@value #LOCATION} parameter.
          */
         public static final ParameterDescriptor<URI> LOCATION_PARAM;
 
         /**
+         * Description of the optional {@value #CREATE} parameter, which may 
be present in writable data store.
+         * This parameter is not included in the descriptor created by {@link 
#build(ParameterBuilder)} default
+         * implementation. It is subclass responsibility to add it if desired, 
only if supported.
+         */
+        public static final ParameterDescriptor<Boolean> CREATE_PARAM;
+
+        /**
          * Description of the optional parameter for character encoding used 
by the data store.
          * This parameter is not included in the descriptor created by {@link 
#build(ParameterBuilder)}
          * default implementation. It is subclass responsibility to add it if 
desired.
@@ -116,6 +123,7 @@ public abstract class URIDataStore exten
         static {
             final ParameterBuilder builder = new ParameterBuilder();
             ENCODING       = 
builder.addName("encoding").setDescription(Resources.formatInternational(Resources.Keys.DataStoreEncoding)).create(Charset.class,
 null);
+            CREATE_PARAM   = builder.addName( CREATE   
).setDescription(Resources.formatInternational(Resources.Keys.DataStoreCreate  
)).create(Boolean.class, null);
             LOCATION_PARAM = builder.addName( LOCATION 
).setDescription(Resources.formatInternational(Resources.Keys.DataStoreLocation)).setRequired(true).create(URI.class,
 null);
         }
 

Modified: 
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/folder/FolderStoreProvider.java
URL: 
http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/folder/FolderStoreProvider.java?rev=1825133&r1=1825132&r2=1825133&view=diff
==============================================================================
--- 
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/folder/FolderStoreProvider.java
 [UTF-8] (original)
+++ 
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/internal/storage/folder/FolderStoreProvider.java
 [UTF-8] Fri Feb 23 15:28:45 2018
@@ -97,7 +97,7 @@ public final class FolderStoreProvider e
         TIMEZONE   = 
builder.addName("timezone").setDescription(Resources.formatInternational(Resources.Keys.DataStoreTimeZone)).setRemarks(remark).create(TimeZone.class,
 null);
         FORMAT     = builder.addName("format"  
).setDescription(Resources.formatInternational(Resources.Keys.DirectoryContentFormatName)).create(String.class,
 null);
         location   = new 
ParameterBuilder(URIDataStore.Provider.LOCATION_PARAM).create(Path.class, null);
-        PARAMETERS = builder.addName(NAME).createGroup(location, LOCALE, 
TIMEZONE, ENCODING, FORMAT);
+        PARAMETERS = builder.addName(NAME).createGroup(location, LOCALE, 
TIMEZONE, ENCODING, FORMAT, URIDataStore.Provider.CREATE_PARAM);
     }
 
     /**
@@ -259,7 +259,7 @@ public final class FolderStoreProvider e
         connector.setOption(OptionKey.ENCODING, pg.getValue(ENCODING));
         final String format = pg.getValue(FORMAT);
         final EnumSet<StandardOpenOption> options = 
EnumSet.noneOf(StandardOpenOption.class);
-        if (format != null) {
+        if (format != null && 
Boolean.TRUE.equals(pg.getValue(URIDataStore.Provider.CREATE_PARAM))) {
             options.add(StandardOpenOption.WRITE);
         }
         return open(connector, format, options);

Modified: 
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
URL: 
http://svn.apache.org/viewvc/sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java?rev=1825133&r1=1825132&r2=1825133&view=diff
==============================================================================
--- 
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
 [UTF-8] (original)
+++ 
sis/branches/JDK8/storage/sis-storage/src/main/java/org/apache/sis/storage/DataStoreProvider.java
 [UTF-8] Fri Feb 23 15:28:45 2018
@@ -83,14 +83,24 @@ public abstract class DataStoreProvider
      * Name of the parameter that specifies whether to allow creation of a new 
{@code DataStore} if none exist
      * at the given location. A parameter named {@value} may be included in 
the group of parameters returned by
      * {@link #getOpenParameters()} if the data store supports write 
operations. The parameter value is often a
-     * {@link Boolean}, but other types are allowed. The default value should 
be {@link Boolean#FALSE} or equivalent.
+     * {@link Boolean} and the default value should be {@link Boolean#FALSE} 
or equivalent.
      *
-     * <p>Implementors are encouraged to define a parameter with this name in 
complement to the {@value #LOCATION}
-     * parameter if write operations are supported. The parameter should be 
defined as optional and typed with a
-     * well-known Java class such as {@link Boolean} or {@link String}. If 
this parameter value is not set or is
-     * set to {@code false}, then the {@link #open(ParameterValueGroup)} 
method should fail if no file or database
-     * exists at the URL or path given by the {@value #LOCATION} parameter. 
Otherwise if this parameter is set to
-     * {@code true}, then the {@code open(…)} method may create files, a 
directory or a database at the given location.</p>
+     * <p>Implementors are encouraged to define an <em>optional</em> parameter 
with this name in complement to the
+     * {@value #LOCATION} parameter <em>only if</em> write operations are 
supported. If this parameter value is not
+     * set or is set to {@code false}, then the {@link 
#open(ParameterValueGroup)} method should fail if no file or
+     * database exists at the URL or path given by the {@value #LOCATION} 
parameter. Otherwise if this parameter is
+     * set to {@code true}, then the {@code open(…)} method may create files, 
a directory or a database at the given
+     * location.</p>
+     *
+     * <div class="note"><b>Relationship with standard file open options</b>
+     * <p>For data stores on file systems, a <code>{@value} = true</code> 
parameter value is equivalent to opening a file
+     * with {@link java.nio.file.StandardOpenOption#CREATE} and {@link 
java.nio.file.StandardOpenOption#APPEND APPEND}.
+     * The other file standard options like {@link 
java.nio.file.StandardOpenOption#CREATE_NEW CREATE_NEW} and
+     * {@link java.nio.file.StandardOpenOption#TRUNCATE_EXISTING 
TRUNCATE_EXISTING} should not be accessible through
+     * this {@value} parameter. The reason is that {@link ParameterValueGroup} 
may be used for storing parameters
+     * permanently (for example in a configuration file or in a database) for 
reopening the same {@link DataStore}
+     * many times. File options designed for being used only once like {@code 
CREATE_NEW} and {@code TRUNCATE_EXISTING}
+     * are incompatible with this usage.</p></div>
      *
      * @see #LOCATION
      * @see #getOpenParameters()


Reply via email to