On 2/5/2013 12:30 PM, Gordon Yorke wrote:
>>> javax.persistence.database-product-name
>>> javax.persistence.database-major-version
>>> javax.persistence.database-minor-version
>>>
>>> javax.persistence.schema-generation.create-source
>>> javax.persistence.schema-generation.drop-source
>>> javax.persistence.schema-generation.create-script-source
>>> javax.persistence.schema-generation.drop-script-source
>>
>> This would be javax.persistence.schema-generation.scripts.create-source and drop-source, right?
> I think it would be confusing to call these javax.persistence.schema-generation.scripts.create-source when they
> reference the actual scripts and are not actions. We could call them
> javax.persistence.schema-generation.database.create-script-source if you need to qualify them but I believe they are
> fine as they are.
OK, thanks. Will keep as in Steve's initial proposal.
>
>>
>> Should the preceding be javax.persistence.schema-generation.database.create-source and drop-source ?
>> Or is that obvious?
>
>
> On 05/02/2013 3:20 PM, Linda DeMichiel wrote:
>> thanks, Steve
>>
>> On 2/5/2013 9:13 AM, Steve Ebersole wrote:
>>> 1) I think the split into database-action and script-action plays much nicer. Nice thought.
>>>
>>> 2) You wrote '* javax.persistence.schema-generation.database-source' in the updated spec section, as a replacement for
>>> javax.persistence.schema-generation-source. IMO this should be named 'javax.persistence.schema-generation.create-source'
>>> instead to pair with the new 'javax.persistence.schema-generation.drop-source'
>>>
>>> 3) I wonder if a better consistent naming scheme would be to use javax.persistence.schema-generation.database.<setting>
>>> and javax.persistence.schema-generation.scripts.<setting>? To me that plays much nicer:
>>>
>>
>> I am fine with this. See the below for minor tweaks/questions.
>> Otherwise, I plan to commit these changes to the spec.
>>
>>> javax.persistence.database-product-name
>>> javax.persistence.database-major-version
>>> javax.persistence.database-minor-version
>>>
>>> javax.persistence.schema-generation.create-source
>>> javax.persistence.schema-generation.drop-source
>>> javax.persistence.schema-generation.create-script-source
>>> javax.persistence.schema-generation.drop-script-source
>>
>> This would be javax.persistence.schema-generation.scripts.create-source and drop-source, right?
>>
>> Should the preceding be javax.persistence.schema-generation.database.create-source and drop-source ?
>> Or is that obvious?
>>
>>> javax.persistence.schema-generation.connection
>>> javax.persistence.schema-generation.create-database-schemas*
>>>
>>> javax.persistence.schema-generation.database.action
>>>
>>> javax.persistence.schema-generation.scripts.action
>>> javax.persistence.schema-generation.scripts.create-target
>>> javax.persistence.schema-generation.scripts.drop-target
>>>
>>> * - I was not clear whether create-database-schemas is meant to describe just database target or scripts target or
>>> both..
>>>
>>
>> Should cover both
>>
>>> 4) WRT "data loading", the question of delimiter is still open. I think this ought to be spelled out in the spec,
>>> otherwise provider portability will be a major problem.
>>>
>>>
>>>
>>> On 02/04/2013 03:49 PM, Linda DeMichiel wrote:
>>>> 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
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>
>