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