Steve, all,
You have raised good questions. To clarify all this up, I am proposing that we
refactor the metadata a bit.
To summarize, I am proposing that we do the following:
1) modify javax.persistence.schema-generation-action to be
javax.persistence.schema-generation.database-action. The property
values and semantics are the same, with the exception that if this
property is not specified, no schema generation actions must be
taken *on the database*.
(2) remove javax.persistence.schema-generation-target and replace with
javax.persistence.schema-generation.script-action. The values of
this property and semantics would be the same as
javax.persistence.schema-generation.database-action, except that this
pertains to scripts only. If this property is not specified, no
scripts will be generated.
(3) To accommodate the feedback about drop execution order,
I think we should add another property,
javax.persistence.schema-generation.drop-source that
is just like javax.persistence.schema-generation-source, but allows
control over dropping the database artifacts and the order in which
this is to occur.
(4) make some minor naming changes to make things more consistent/clearer.
More formally, the resulting spec section would look like this:
Section 8.2.1.9 would be updated similarly, as appropriate.
[Section 9.4]
* javax.persistence.schema-generation.database-action
The javax.persistence.schema-generation.database-action property
specifies the action to be taken by the persistence provider with
regard to the database artifacts. The values for this property are
"none", "create", "drop-and-create", "drop". If the
javax.persistence.schema-generation.database-action property is not
specified, no schema generation actions must be taken on the database.
* javax.persistence.schema-generation.script-action
The javax.persistence.schema-generation.script-action property
specifies which scripts are to be generated by the persistence
provider. The values for this property are "none", "create",
"drop-and-create", "drop". Scripts will only be generated if script
targets are specified. If this property is not specified, no scripts
will be generated.
* javax.persistence.schema-generation.database-source
The javax.persistence.schema-generation.database-source property
specifies whether the creation of database artifacts is to occur on
the basis of the object/relational mapping metadata, DDL script, or a
combination of the two. The values for this property are "metadata",
"script", "metadata-then-script", "script-then-metadata". If this
property is not specified, and a script is specified by the
javax.persistence.schema-generation.create-script-source property,
the script (only) will be used for schema generation; otherwise if
this property is not specified, schema generation will occur on the
basis of the object/relational mapping metadata (only). The
"metadata-then-script" and "script-then-metadata" values specify that a
combination of metadata and script is to be used and the order in
which this use is to occur. If either of these values is specified and
the resulting database actions are not disjoint, the results are
undefined and schema generation may fail.
* javax.persistence.schema-generation.drop-source
The javax.persistence.schema-generation.drop-source property specifies
whether the dropping of database artifacts is to occur on the basis of
the object/relational mapping metadata, DDL script, or a combination
of the two. The values for this property are "metadata", "script",
"metadata-then-script", "script-then-metadata". If this property is
not specified, and a script is specified by the
javax.persistence.schema-generation.drop-script-source property,
the script (only) will be used for the dropping of database artifacts;
otherwise if this property is not specified, the dropping of database
artifacts will occur on the basis of the object/relational mapping
metadata (only). The "metadata-then-script" and "script-then-metadata"
values specify that a combination of metadata and script is to be used
and the order in which this use is to occur. If either of these values
is specified and the resulting database actions are not disjoint, the
results are undefined and the dropping of database artifacts may fail.
* javax.persistence.schema-generation.create-database-schemas
In Java EE environments, it is anticipated that the Java EE platform
provider may wish to control the creation of database schemas rather
than delegate this task to the persistence provider. The
javax.persistence.schema-generation.create-database-schemas property
specifies whether the persistence provider is to create the database
schema(s) in addition to creating database objects such as tables,
sequences, constraints, etc. The value of this boolean property should
be set to true if the persistence provider is to create schemas in the
database or to generate DDL that contains "CREATE SCHEMA" commands. If
this property is not supplied, the provider should not attempt to
create database schemas. This property may also be specified in Java
SE environments.
* javax.persistence.schema-generation.create-script-target,
javax.persistence.schema-generation.drop-script-target
If scripts are to be generated, the target locations for the writing
of these scripts must be specified.
The javax.persistence.schema-generation.create-script-target property
specifies a java.IO.Writer configured for use by the persistence
provider for output of the DDL script or a string specifying the file
URL for the DDL script. This property should only be specified if
scripts are to be generated.
The javax.persistence.schema-generation.drop-script-target property
specifies a java.IO.Writer configured for use by the persistence
provider for output of the DDL script or a string specifying the file
URL for the DDL script. This property should only be specified if
scripts are to be generated.
* javax.persistence.database-product-name,
javax.persistence.database-major-version,
javax.persistence.database-minor-version
If scripts are to be generated by the persistence provider and a
connection to the target database is not supplied, the
javax.persistence.database-product-name property must be
specified. The value of this property should be the value returned for
the target database by the JDBC DatabaseMetaData method
getDatabaseProductName. If sufficient database version information is
not included in the result of this method, the javax.persistence.
database-major-version and javax.persistence.database-minor-version
properties should be specified as needed. These should contain the
values returned by the JDBC getDatabaseMajorVersion and
getDatabaseMinorVersion methods respectively.
* javax.persistence.schema-generation.create-script-source,
* javax.persistence.schema-generation.drop-script-source
The javax.persistence.schema-generation.create-script-source and
javax.persistence.schema-generation.drop-script-source properties are
used for script execution. In Java EE container environments, it is
generally expected that the container will be responsible for
executing DDL scripts, although the container is permitted to delegate
this task to the persistence provider. If DDL scripts are to be used
in Java SE environments or if the Java EE container delegates the
execution of scripts to the persistence provider, these properties
must be specified. The javax.persistence.schema-generation.create-script-source
property specifies a java.IO.Reader configured for reading of the DDL script or
a string designating a file URL for the DDL script.
The javax.persistence.schema-generation.drop-script-source property
specifies a java.IO.Reader configured for reading of the DDL script or
a string designating a file URL for the DDL script.
* javax.persistence.schema-generation.connection
The javax.persistence.schema-generation.connection property specifies
the JDBC connection to be used for schema generation. This is intended
for use in Java EE environments, where the platform provider may want
to control the database privileges that are available to the
persistence provider. This connection is provided by the container,
and should be closed by the container when the schema generation
request or entity manager factory creation completes. The connection
provided must have credentials sufficient for the persistence provider
to carry out the requested actions. If this property is not specified,
the persistence provider should use the DataSource that has otherwise
been provided.
[subsection 9.4.1] Data Loading
Data loading, by means of the use of SQL scripts, may occur as part of
the schema generation process after the creation of the database
artifacts or independently of schema generation. The specification of
the javax.persistence.sql-load-script-source controls whether data
loading will occur.
* javax.persistence.sql-load-script-source
In Java EE container environments, it is generally expected that the
container will be responsible for executing data load scripts,
although the container is permitted to delegate this task to the
persistence provider. If a load script is to be used in Java SE
environments or if the Java EE container delegates the execution of
the load script to the persistence provider, this property must be
specified. The javax.persistence.sql-load-script-source property
specifies a java.IO.Reader configured for reading of the SQL load
script for database initialization or a string designating a file URL
for the script.
On 2/1/2013 7:23 AM, Steve Ebersole wrote:
> I guess what I was getting at yesterday is that it *seems* as if the intent is that
> 'javax.persistence.ddl-create-script-target' and 'javax.persistence.ddl-drop-script-target':
> 1) need to be specified either both together or neither
> 2) Control:
> 2.a) whether scripts are generated
> 2.b) what types of scripts are generated.
>
> So if I have:
>
> javax.persistence.schema-generation-action=create
> javax.persistence.schema-generation-target=database-and-scripts
> javax.persistence.ddl-create-script-target=<something>
> javax.persistence.ddl-drop-script-target=<something>
>
> the "action=create" bit really only describes the database target side of things. On the script target side, both create
> and drop are created.
>
> To me at least that is not the most intuitive set up. If I say "action=create", why are the drop scripts being generated?
>
>
>
> On Thu 31 Jan 2013 03:03:43 PM CST, Steve Ebersole wrote:
>> Well the confusion IMO as a user is that I specifically asked for only
>> creation scripts to be generated, but got both creation and drop
>> scripts. Thats not going to change by making schema-generation-target
>> required. Even this is still confusing:
>>
>> javax.persistence.schema-generation-action=create
>> javax.persistence.schema-generation-target=scripts
>> javax.persistence.ddl-create-script-target=<something>
>> javax.persistence.ddl-drop-script-target=<something>
>>
>>
>> because i would not expect to get a drop script. But if I read the
>> other parts of the spec correctly, the following actually results in
>> an exception:
>>
>> javax.persistence.schema-generation-action=create
>> javax.persistence.schema-generation-target=scripts
>> javax.persistence.ddl-create-script-target=<something>
>>
>> The exception is because 'javax.persistence.ddl-drop-script-target' is
>> not specified, again even though i just said I only want create
>> scripts generated.
>>
>> On Thu 31 Jan 2013 02:13:20 PM CST, Linda DeMichiel wrote:
>>>
>>>
>>> On 1/31/2013 11:52 AM, Steve Ebersole wrote:
>>>> I also am not sure about this passage in discussing
>>>> 'javax.persistence.ddl-create-script-target' and
>>>> 'javax.persistence.ddl-drop-script-target':
>>>>
>>>> <quote>
>>>> The persistence provider must produce both create and drop scripts if
>>>> the corresponding
>>>> DDL targets are specified. This is independent of whether a drop
>>>> action is included in the
>>>> value passed for the javax.persistence.schema-generation-action
>>>> property.
>>>> </quote>
>>>>
>>>> To me, this sounds like you are saying that the following config will
>>>> generate both create and drop scripts:
>>>>
>>>> javax.persistence.schema-generation-action=create
>>>> javax.persistence.ddl-create-script-target=<something>
>>>> javax.persistence.ddl-drop-script-target=<something>
>>>>
>>>> even though the config explicitly specified just create scripts. Is
>>>> that your intent?
>>>>
>>>
>>> yes
>>>
>>>> Same for:
>>>>
>>>> javax.persistence.schema-generation-action=drop
>>>> javax.persistence.ddl-create-script-target=<something>
>>>> javax.persistence.ddl-drop-script-target=<something>
>>>>
>>>> that is supposed to generate both create and drop scripts?
>>>>
>>>
>>> yes
>>>
>>>>
>>>> Perhaps the reasoning is that
>>>> javax.persistence.schema-generation-action is really just geared
>>>> towards
>>>> javax.persistence.schema-generation-action=database.
>>>
>>> partially. also it was intended to control whether any action would
>>> be taken.
>>>
>>> I'm thinking that all this might be clearer if we required
>>> schema-generation-target to be specified.
>>>
>>> But if that is the case, maybe we ought to rename the setting to be
>>>> more explicit of that fact or at least document it in the discussion
>>>> of 'javax.persistence.schema-generation-action'
>>>>
>>>>
>>>> On 01/31/2013 01:13 PM, Steve Ebersole wrote:
>>>>> One quick question.
>>>>>
>>>>> For 'javax.persistence.schema-generation-source' values of
>>>>> metadata-then-scripts and scripts-then-metadata is the
>>>>> order the same for both create and drop?
>>>>>
>>>>> I can envision a situation, for example, with metadata-then-scripts
>>>>> where the metadata creates a table and then the
>>>>> script creates a procedure. I am not sure that all databases will
>>>>> allow you to drop the table if other database
>>>>> objects refer to it. Would it be better to say that the defined
>>>>> order (x-then-y) applies to create, but the reverse
>>>>> order (y-then-x) applies to drop?
>>>>>
>>>>>
>>>>> On 01/31/2013 12:49 PM, Steve Ebersole wrote:
>>>>>> These look great. Thanks Linda.
>>>>>>
>>>>>> On 01/28/2013 05:14 PM, Linda DeMichiel wrote:
>>>>>>> There are currently a few open issues in schema generation that need
>>>>>>> clarification. These pertain to sections 9.4 ("Schema generation")
>>>>>>> and 8.2.1.9 ("properties") in the spec.
>>>>>>>
>>>>>>> I've made some clarifications and proposed some additions to the
>>>>>>> metadata for schema generation as described below. The draft I've
>>>>>>> just uploaded reflects these changes
>>>>>>> (http://java.net/projects/jpa-spec/downloads/download/JavaPersistence01282013.pdf).
>>>>>>>
>>>>>>>
>>>>>>> Please review these sections and post any feedback. Changes are
>>>>>>> summarized below.
>>>>>>>
>>>>>>> ----
>>>>>>>
>>>>>>> Section 9.4
>>>>>>>
>>>>>>> This section isn't sufficiently clear about requirements for the
>>>>>>> specification of schema-generation-action and
>>>>>>> schema-generation-target.
>>>>>>>
>>>>>>> I've clarified that schema-generation-action must be specified or no
>>>>>>> actions will be taken. This was an assumed default in the current
>>>>>>> public draft, but IMO not sufficiently explicit.
>>>>>>>
>>>>>>> Given the clarification to schema-generation-action, I think it now
>>>>>>> makes sense for schema-generation-target to have default values.
>>>>>>> That is, if script targets are specified by the properties for
>>>>>>> scripts,
>>>>>>> then generation actions should default into scripts. If not, actions
>>>>>>> should be directly into the database.
>>>>>>>
>>>>>>> The current public draft assumes that if script sources are
>>>>>>> specified,
>>>>>>> generation should occur from scripts exclusively; and conversely, if
>>>>>>> script sources are not specified, generation should occur
>>>>>>> exclusively
>>>>>>> from the ORM metadata. I've gotten feedback that this wasn't
>>>>>>> sufficiently
>>>>>>> flexible, and that we should support a combination of ORM and script
>>>>>>> sources. (For example, consider the case where generation should
>>>>>>> occur
>>>>>>> from scripts, but it is desirable to add stored procedures to the
>>>>>>> database.)
>>>>>>> I therefore propose that we add a schema-generation-source property
>>>>>>> that will support such combination. Again, if script sources are
>>>>>>> specified
>>>>>>> by the properties for scripts, then generation will default to
>>>>>>> use of
>>>>>>> only script sources; if script sources aren't specified, then
>>>>>>> generation
>>>>>>> will default from the ORM metadata.
>>>>>>>
>>>>>>> I've also received feedback (from our JPA/EE integration engineer)
>>>>>>> that
>>>>>>> we need to specify that in Java EE environments that strings
>>>>>>> corresponding
>>>>>>> to file URLs must use absolute (and not relative) paths. I've
>>>>>>> added that
>>>>>>> clarification as well.
>>>>>>>
>>>>>>>
>>>>>>> Section 8.2.1.9
>>>>>>>
>>>>>>> In the current public draft, this section lacks information as to
>>>>>>> how
>>>>>>> script locations are specified. I've added a clarification that
>>>>>>> scripts packaged as part of the application must be specified
>>>>>>> relative
>>>>>>> to the root of the persistence unit, as we do for other packaged
>>>>>>> artifacts. I've also added a clarification about the expectations
>>>>>>> for
>>>>>>> use of file URLs in Java EE environments as above.
>>>>>>>
>>>>>>> Finally, when I wrote this up initially, I was reluctant to add
>>>>>>> metadata for schema generation actions (including targets) because I
>>>>>>> believed that such metadata should not be specific to the
>>>>>>> persistence
>>>>>>> unit definition itself. It seems however that people expect that the
>>>>>>> use of these properties (as specified in section 9.4) will be
>>>>>>> available anyway, whether they are specified in the spec document or
>>>>>>> not, and that some vendors will support these anyway as well.
>>>>>>> Further, this additional metadata may facilitate ease of use in
>>>>>>> prototyping/development environments. I've therefore added these
>>>>>>> properties into 8.2.1.9. If you disagree, please speak up.
>>>>>>>
>>>>>>>
>>>>>>> thanks,
>>>>>>>
>>>>>>> -Linda
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>
>>>>>
>>>>