[jira] Created: (JDO-615) MetaData specification API

MetaData specification API
--------------------------

                 Key: JDO-615
                 URL: https://issues.apache.org/jira/browse/JDO-615
             Project: JDO
          Issue Type: New Feature
            Reporter: Andy Jefferson
             Fix For: JDO 2 maintenance release 3


We can specify MetaData via XML or annotations. The only way missing is via an API. I propose mirroring the XML structure with interfaces of the form

public interface MetaData
{
    addExtension(String key, String value);
    removeExtension(String key, String value);
    ...
}

public interface FileMetaData
{
    addPackage(PackageMetaData pmd);
    ...
}

public interface PackageMetaData
{
    addClass(ClassMetaData cmd)
    ...
}

public interface ClassMetaData
{
    addField(FieldMetaData fmd)
    ...
}

public interface FieldMetaData
{
    setInheritance(InheritanceMetaData inhmd)
    ...
}

and so on.


We would then require a method on the PMF to register the metadata.


If there are no objections to such a feature I'll propose a patch to try to provide all current JDO2 capabilities.

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

     [ https://issues.apache.org/jira/browse/JDO-615?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Andy Jefferson updated JDO-615:
-------------------------------

    Attachment: jdometadata.patch

Work-in-progress patch to provide javax.jdo.metadata for use in having an API for metadata.
Some classes still need completion to match the DTD/XSD.

Maybe FileMetaData should be called JDOMetaData?

I've included copies of some enums under javax.jdo.annotations. Maybe they should only be under javax.jdo.metadata ? but what about backwards compatibility?

Interface with PMF could be as simple as
pmf.registerMetaData(FileMetaData md);

or we could provide access to current metadata too, so
pmf.getMetaData(String className);

> MetaData specification API
> --------------------------
>
>                 Key: JDO-615
>                 URL: https://issues.apache.org/jira/browse/JDO-615
>             Project: JDO
>          Issue Type: New Feature
>            Reporter: Andy Jefferson
>             Fix For: JDO 2 maintenance release 3
>
>         Attachments: jdometadata.patch
>
>
> We can specify MetaData via XML or annotations. The only way missing is via an API. I propose mirroring the XML structure with interfaces of the form
> public interface MetaData
> {
>     addExtension(String key, String value);
>     removeExtension(String key, String value);
>     ...
> }
> public interface FileMetaData
> {
>     addPackage(PackageMetaData pmd);
>     ...
> }
> public interface PackageMetaData
> {
>     addClass(ClassMetaData cmd)
>     ...
> }
> public interface ClassMetaData
> {
>     addField(FieldMetaData fmd)
>     ...
> }
> public interface FieldMetaData
> {
>     setInheritance(InheritanceMetaData inhmd)
>     ...
> }
> and so on.
> We would then require a method on the PMF to register the metadata.
> If there are no objections to such a feature I'll propose a patch to try to provide all current JDO2 capabilities.

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

     [ https://issues.apache.org/jira/browse/JDO-615?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Andy Jefferson updated JDO-615:
-------------------------------

    Attachment:     (was: jdometadata.patch)

> MetaData specification API
> --------------------------
>
>                 Key: JDO-615
>                 URL: https://issues.apache.org/jira/browse/JDO-615
>             Project: JDO
>          Issue Type: New Feature
>            Reporter: Andy Jefferson
>             Fix For: JDO 2 maintenance release 3
>
>
> We can specify MetaData via XML or annotations. The only way missing is via an API. I propose mirroring the XML structure with interfaces of the form
> public interface MetaData
> {
>     addExtension(String key, String value);
>     removeExtension(String key, String value);
>     ...
> }
> public interface FileMetaData
> {
>     addPackage(PackageMetaData pmd);
>     ...
> }
> public interface PackageMetaData
> {
>     addClass(ClassMetaData cmd)
>     ...
> }
> public interface ClassMetaData
> {
>     addField(FieldMetaData fmd)
>     ...
> }
> public interface FieldMetaData
> {
>     setInheritance(InheritanceMetaData inhmd)
>     ...
> }
> and so on.
> We would then require a method on the PMF to register the metadata.
> If there are no objections to such a feature I'll propose a patch to try to provide all current JDO2 capabilities.

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

     [ https://issues.apache.org/jira/browse/JDO-615?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Andy Jefferson updated JDO-615:
-------------------------------

    Attachment: jdometadata-2.patch

Updated patch for basic MetaData bean-style components. Maybe some attributes not yet present - please comment.
Also requires a MetaDataFactory for creating the implementation of each type, so we could have
pmf.getMetaDataManager()
which returns an implementation of "javax.jdo.metadata.MetaDataManager" (to be defined) and which has a series of factory methods for creating the implementations of the metadata components. Also has a method registerMetaData(...) allowing users to hook in their dyanmically created metadata.

> MetaData specification API
> --------------------------
>
>                 Key: JDO-615
>                 URL: https://issues.apache.org/jira/browse/JDO-615
>             Project: JDO
>          Issue Type: New Feature
>            Reporter: Andy Jefferson
>             Fix For: JDO 2 maintenance release 3
>
>         Attachments: jdometadata-2.patch
>
>
> We can specify MetaData via XML or annotations. The only way missing is via an API. I propose mirroring the XML structure with interfaces of the form
> public interface MetaData
> {
>     addExtension(String key, String value);
>     removeExtension(String key, String value);
>     ...
> }
> public interface FileMetaData
> {
>     addPackage(PackageMetaData pmd);
>     ...
> }
> public interface PackageMetaData
> {
>     addClass(ClassMetaData cmd)
>     ...
> }
> public interface ClassMetaData
> {
>     addField(FieldMetaData fmd)
>     ...
> }
> public interface FieldMetaData
> {
>     setInheritance(InheritanceMetaData inhmd)
>     ...
> }
> and so on.
> We would then require a method on the PMF to register the metadata.
> If there are no objections to such a feature I'll propose a patch to try to provide all current JDO2 capabilities.

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

     [ https://issues.apache.org/jira/browse/JDO-615?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Andy Jefferson updated JDO-615:
-------------------------------

    Attachment: jdometadata-3.patch

Further update with simple factory interface for generating metadata components. Alternative approach would be to single method on MetaDataManager newFileMetaData(), and then have a method on each parent component to create the subcomponents.

> MetaData specification API
> --------------------------
>
>                 Key: JDO-615
>                 URL: https://issues.apache.org/jira/browse/JDO-615
>             Project: JDO
>          Issue Type: New Feature
>            Reporter: Andy Jefferson
>             Fix For: JDO 2 maintenance release 3
>
>         Attachments: jdometadata-3.patch
>
>
> We can specify MetaData via XML or annotations. The only way missing is via an API. I propose mirroring the XML structure with interfaces of the form
> public interface MetaData
> {
>     addExtension(String key, String value);
>     removeExtension(String key, String value);
>     ...
> }
> public interface FileMetaData
> {
>     addPackage(PackageMetaData pmd);
>     ...
> }
> public interface PackageMetaData
> {
>     addClass(ClassMetaData cmd)
>     ...
> }
> public interface ClassMetaData
> {
>     addField(FieldMetaData fmd)
>     ...
> }
> public interface FieldMetaData
> {
>     setInheritance(InheritanceMetaData inhmd)
>     ...
> }
> and so on.
> We would then require a method on the PMF to register the metadata.
> If there are no objections to such a feature I'll propose a patch to try to provide all current JDO2 capabilities.

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

     [ https://issues.apache.org/jira/browse/JDO-615?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Andy Jefferson updated JDO-615:
-------------------------------

    Attachment:     (was: jdometadata-2.patch)

> MetaData specification API
> --------------------------
>
>                 Key: JDO-615
>                 URL: https://issues.apache.org/jira/browse/JDO-615
>             Project: JDO
>          Issue Type: New Feature
>            Reporter: Andy Jefferson
>             Fix For: JDO 2 maintenance release 3
>
>         Attachments: jdometadata-3.patch
>
>
> We can specify MetaData via XML or annotations. The only way missing is via an API. I propose mirroring the XML structure with interfaces of the form
> public interface MetaData
> {
>     addExtension(String key, String value);
>     removeExtension(String key, String value);
>     ...
> }
> public interface FileMetaData
> {
>     addPackage(PackageMetaData pmd);
>     ...
> }
> public interface PackageMetaData
> {
>     addClass(ClassMetaData cmd)
>     ...
> }
> public interface ClassMetaData
> {
>     addField(FieldMetaData fmd)
>     ...
> }
> public interface FieldMetaData
> {
>     setInheritance(InheritanceMetaData inhmd)
>     ...
> }
> and so on.
> We would then require a method on the PMF to register the metadata.
> If there are no objections to such a feature I'll propose a patch to try to provide all current JDO2 capabilities.

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

    [ https://issues.apache.org/jira/browse/JDO-615?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12651966#action_12651966 ]

Andy Jefferson commented on JDO-615:
------------------------------------

To demonstrate a typical use-case for this API, have a look at this :-
http://www.jpox.org/servlet/wiki/pages/viewpage.action?pageId=6619188
This demonstrates the dynamic generation of a class in memory. We then create MetaData for it (DataNucleus API in this case). We then enhance the in-memory class. We finally use the in-memory enhanced class (and metadata) at runtime.

JDO-591 will standardise the enhancer API, and JDO-615 will standardise the MetaData API, hence going a long way towards providing the full process without touching a particular vendors classes.

> MetaData specification API
> --------------------------
>
>                 Key: JDO-615
>                 URL: https://issues.apache.org/jira/browse/JDO-615
>             Project: JDO
>          Issue Type: New Feature
>            Reporter: Andy Jefferson
>             Fix For: JDO 2 maintenance release 3
>
>         Attachments: jdometadata-3.patch
>
>
> We can specify MetaData via XML or annotations. The only way missing is via an API. I propose mirroring the XML structure with interfaces of the form
> public interface MetaData
> {
>     addExtension(String key, String value);
>     removeExtension(String key, String value);
>     ...
> }
> public interface FileMetaData
> {
>     addPackage(PackageMetaData pmd);
>     ...
> }
> public interface PackageMetaData
> {
>     addClass(ClassMetaData cmd)
>     ...
> }
> public interface ClassMetaData
> {
>     addField(FieldMetaData fmd)
>     ...
> }
> public interface FieldMetaData
> {
>     setInheritance(InheritanceMetaData inhmd)
>     ...
> }
> and so on.
> We would then require a method on the PMF to register the metadata.
> If there are no objections to such a feature I'll propose a patch to try to provide all current JDO2 capabilities.

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

    [ https://issues.apache.org/jira/browse/JDO-615?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12652505#action_12652505 ]

Craig Russell commented on JDO-615:
-----------------------------------

Just some high level comments for right now.

In order to mirror the xml metadata, you would need to start with a top level metadata root, corresponding to the jdo element. You could construct this from the JDOHelper, e.g. public JDOMetadata newJDOMetadata();

Then, JDOMetadata would have methods newPackageMetadata(String name), newQueryMetadata(String name), and newFetchPlanMetadata(String name).

PackageMetadata would then have methods newInterfaceMetadata, newClassMetadata, and newSequenceMetadata.

If you use method chaining instead of constructors, then you could change this example to be more self-describing:

    ClassMetaData cmd = dmdf.newClassObject(pmd,"Client", IdentityType.DATASTORE.toString(), null,
            Boolean.TRUE.toString(), Boolean.TRUE.toString(), Boolean.FALSE.toString(),
            ClassPersistenceModifier.PERSISTENCE_CAPABLE.toString(), null, null, null, "CLIENT", null);

pkgMetadata.newClassMetadata("Client")
.setIdentityType(IdentityType.DATASTORE)
.setPersistenceCapableSuperclass("Person");

Using the newClassMetadata construction would enforce the rule that a class can be a member of only one package, so you can neither forget to assign the class to a package nor add the class to more than one package.

If you want to enforce setting the required metadata, the newXXX could do this, e.g. for sequence metadata, the name and strategy are required:
packageMetadata.newSequence("SQ1244", SequenceStrategy.CONTIGUOUS);

But most metadata is optional with reasonable defaults.

For boolean properties, you might use Boolean as parameters/return values instead. Java 5 will automatically convert the setXXX parameters for you, but the getXXX will return a tristate value which is needed to distinguish between the user setting a value and not. A boolean return type doesn't allow this.

Finally, note that in the javax.jdo.annotations package we already have enums for the metadata. So there's no need to repeat them. The only awkward thing is that they would be referenced from the metadata package. But repeating their definitions in multiple packages seems worse.

> MetaData specification API
> --------------------------
>
>                 Key: JDO-615
>                 URL: https://issues.apache.org/jira/browse/JDO-615
>             Project: JDO
>          Issue Type: New Feature
>            Reporter: Andy Jefferson
>             Fix For: JDO 2 maintenance release 3
>
>         Attachments: jdometadata-3.patch
>
>
> We can specify MetaData via XML or annotations. The only way missing is via an API. I propose mirroring the XML structure with interfaces of the form
> public interface MetaData
> {
>     addExtension(String key, String value);
>     removeExtension(String key, String value);
>     ...
> }
> public interface FileMetaData
> {
>     addPackage(PackageMetaData pmd);
>     ...
> }
> public interface PackageMetaData
> {
>     addClass(ClassMetaData cmd)
>     ...
> }
> public interface ClassMetaData
> {
>     addField(FieldMetaData fmd)
>     ...
> }
> public interface FieldMetaData
> {
>     setInheritance(InheritanceMetaData inhmd)
>     ...
> }
> and so on.
> We would then require a method on the PMF to register the metadata.
> If there are no objections to such a feature I'll propose a patch to try to provide all current JDO2 capabilities.

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

    [ https://issues.apache.org/jira/browse/JDO-615?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12652720#action_12652720 ]

Andy Jefferson commented on JDO-615:
------------------------------------

I included a top level metadata, just I called it FileMetaData, with the comment above "Maybe FileMetaData should be called JDOMetaData?" ;-)

If you create JDOMetaData via JDOHelper then how is JDOHelper to know what the implementation of JDOMetaData is that it should create? (Could be done via META-INF/services entry).

No problem with using "newXXXMetaData" on MetaData classes instead of having factory methods.

> MetaData specification API
> --------------------------
>
>                 Key: JDO-615
>                 URL: https://issues.apache.org/jira/browse/JDO-615
>             Project: JDO
>          Issue Type: New Feature
>            Reporter: Andy Jefferson
>             Fix For: JDO 2 maintenance release 3
>
>         Attachments: jdometadata-3.patch
>
>
> We can specify MetaData via XML or annotations. The only way missing is via an API. I propose mirroring the XML structure with interfaces of the form
> public interface MetaData
> {
>     addExtension(String key, String value);
>     removeExtension(String key, String value);
>     ...
> }
> public interface FileMetaData
> {
>     addPackage(PackageMetaData pmd);
>     ...
> }
> public interface PackageMetaData
> {
>     addClass(ClassMetaData cmd)
>     ...
> }
> public interface ClassMetaData
> {
>     addField(FieldMetaData fmd)
>     ...
> }
> public interface FieldMetaData
> {
>     setInheritance(InheritanceMetaData inhmd)
>     ...
> }
> and so on.
> We would then require a method on the PMF to register the metadata.
> If there are no objections to such a feature I'll propose a patch to try to provide all current JDO2 capabilities.

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

     [ https://issues.apache.org/jira/browse/JDO-615?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Andy Jefferson updated JDO-615:
-------------------------------

    Attachment:     (was: jdometadata-3.patch)

> MetaData specification API
> --------------------------
>
>                 Key: JDO-615
>                 URL: https://issues.apache.org/jira/browse/JDO-615
>             Project: JDO
>          Issue Type: New Feature
>            Reporter: Andy Jefferson
>             Fix For: JDO 2 maintenance release 3
>
>         Attachments: jdometadata-4.patch
>
>
> We can specify MetaData via XML or annotations. The only way missing is via an API. I propose mirroring the XML structure with interfaces of the form
> public interface MetaData
> {
>     addExtension(String key, String value);
>     removeExtension(String key, String value);
>     ...
> }
> public interface FileMetaData
> {
>     addPackage(PackageMetaData pmd);
>     ...
> }
> public interface PackageMetaData
> {
>     addClass(ClassMetaData cmd)
>     ...
> }
> public interface ClassMetaData
> {
>     addField(FieldMetaData fmd)
>     ...
> }
> public interface FieldMetaData
> {
>     setInheritance(InheritanceMetaData inhmd)
>     ...
> }
> and so on.
> We would then require a method on the PMF to register the metadata.
> If there are no objections to such a feature I'll propose a patch to try to provide all current JDO2 capabilities.

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

     [ https://issues.apache.org/jira/browse/JDO-615?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Andy Jefferson updated JDO-615:
-------------------------------

    Attachment: jdometadata-4.patch

Updated javax.jdo.metadata :-
1. Remove many enums dupd from annotations, as per my previous comments on this JIRA
2. Renamed FileMetaData to JDOMetaData
3. Added FetchPlanMetaData
4. Added many sub metadata components
5. Changed add/set methods to do the creation of metadata objects as per Craig comments.
6. Updated MetaDataManager to fit above (still has creator for JDOMetaData currently but this could move to JDOHelper at some stage)

> MetaData specification API
> --------------------------
>
>                 Key: JDO-615
>                 URL: https://issues.apache.org/jira/browse/JDO-615
>             Project: JDO
>          Issue Type: New Feature
>            Reporter: Andy Jefferson
>             Fix For: JDO 2 maintenance release 3
>
>         Attachments: jdometadata-4.patch
>
>
> We can specify MetaData via XML or annotations. The only way missing is via an API. I propose mirroring the XML structure with interfaces of the form
> public interface MetaData
> {
>     addExtension(String key, String value);
>     removeExtension(String key, String value);
>     ...
> }
> public interface FileMetaData
> {
>     addPackage(PackageMetaData pmd);
>     ...
> }
> public interface PackageMetaData
> {
>     addClass(ClassMetaData cmd)
>     ...
> }
> public interface ClassMetaData
> {
>     addField(FieldMetaData fmd)
>     ...
> }
> public interface FieldMetaData
> {
>     setInheritance(InheritanceMetaData inhmd)
>     ...
> }
> and so on.
> We would then require a method on the PMF to register the metadata.
> If there are no objections to such a feature I'll propose a patch to try to provide all current JDO2 capabilities.

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

    [ https://issues.apache.org/jira/browse/JDO-615?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12652840#action_12652840 ]

Craig Russell commented on JDO-615:
-----------------------------------

> If you create JDOMetaData via JDOHelper then how is JDOHelper to know what the implementation of JDOMetaData is that it should create? (Could be done via META-INF/services entry).

Right. So maybe the JDOMetadata factory method belongs on PersistenceManagerFactory.

> 6. Updated MetaDataManager to fit above (still has creator for JDOMetaData currently but this could move to JDOHelper at some stage)

If you have newXXX methods you don't need a MetadataManager at all.

One more "big" thing. Metadata shouldn't be camel case. It's a real word, not two words that need a camel in the middle. See http://en.wikipedia.org/wiki/Metadata. So I'd really prefer lower-casing the "d". (Note how hard it is to remember the capital "s" in DataStore?)

> MetaData specification API
> --------------------------
>
>                 Key: JDO-615
>                 URL: https://issues.apache.org/jira/browse/JDO-615
>             Project: JDO
>          Issue Type: New Feature
>            Reporter: Andy Jefferson
>             Fix For: JDO 2 maintenance release 3
>
>         Attachments: jdometadata-4.patch
>
>
> We can specify MetaData via XML or annotations. The only way missing is via an API. I propose mirroring the XML structure with interfaces of the form
> public interface MetaData
> {
>     addExtension(String key, String value);
>     removeExtension(String key, String value);
>     ...
> }
> public interface FileMetaData
> {
>     addPackage(PackageMetaData pmd);
>     ...
> }
> public interface PackageMetaData
> {
>     addClass(ClassMetaData cmd)
>     ...
> }
> public interface ClassMetaData
> {
>     addField(FieldMetaData fmd)
>     ...
> }
> public interface FieldMetaData
> {
>     setInheritance(InheritanceMetaData inhmd)
>     ...
> }
> and so on.
> We would then require a method on the PMF to register the metadata.
> If there are no objections to such a feature I'll propose a patch to try to provide all current JDO2 capabilities.

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

    [ https://issues.apache.org/jira/browse/JDO-615?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12652846#action_12652846 ]

Andy Jefferson commented on JDO-615:
------------------------------------

If you create JDOMetaData via a services entry and there are more than 1 possible in the CLASSPATH how does JDOHelper know that it is picking the right one that is compatible with the JDO implementation that will be used? e.g an app using JDO impl 1 for legacy module 1, and JDO impl 2 for new module 2.
While all implementations of XXXMetadata will implement it, it is reasonable for a JDO implementation to only accept its own implementation of the XXXMetadata interfaces to be registered.

Regarding spelling : No comment (to be made by me on American spellings ;-) )

> MetaData specification API
> --------------------------
>
>                 Key: JDO-615
>                 URL: https://issues.apache.org/jira/browse/JDO-615
>             Project: JDO
>          Issue Type: New Feature
>            Reporter: Andy Jefferson
>             Fix For: JDO 2 maintenance release 3
>
>         Attachments: jdometadata-4.patch
>
>
> We can specify MetaData via XML or annotations. The only way missing is via an API. I propose mirroring the XML structure with interfaces of the form
> public interface MetaData
> {
>     addExtension(String key, String value);
>     removeExtension(String key, String value);
>     ...
> }
> public interface FileMetaData
> {
>     addPackage(PackageMetaData pmd);
>     ...
> }
> public interface PackageMetaData
> {
>     addClass(ClassMetaData cmd)
>     ...
> }
> public interface ClassMetaData
> {
>     addField(FieldMetaData fmd)
>     ...
> }
> public interface FieldMetaData
> {
>     setInheritance(InheritanceMetaData inhmd)
>     ...
> }
> and so on.
> We would then require a method on the PMF to register the metadata.
> If there are no objections to such a feature I'll propose a patch to try to provide all current JDO2 capabilities.

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

    [ https://issues.apache.org/jira/browse/JDO-615?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12652850#action_12652850 ]

Andy Jefferson commented on JDO-615:
------------------------------------

Maybe best to just skip the whole services thing for JDOMetaData. Just add the following to the PMF (and JDOEnhancer)

JDOMetadata newMetadata()
void registerMetadata(JDOMetadata)

> MetaData specification API
> --------------------------
>
>                 Key: JDO-615
>                 URL: https://issues.apache.org/jira/browse/JDO-615
>             Project: JDO
>          Issue Type: New Feature
>            Reporter: Andy Jefferson
>             Fix For: JDO 2 maintenance release 3
>
>         Attachments: jdometadata-4.patch
>
>
> We can specify MetaData via XML or annotations. The only way missing is via an API. I propose mirroring the XML structure with interfaces of the form
> public interface MetaData
> {
>     addExtension(String key, String value);
>     removeExtension(String key, String value);
>     ...
> }
> public interface FileMetaData
> {
>     addPackage(PackageMetaData pmd);
>     ...
> }
> public interface PackageMetaData
> {
>     addClass(ClassMetaData cmd)
>     ...
> }
> public interface ClassMetaData
> {
>     addField(FieldMetaData fmd)
>     ...
> }
> public interface FieldMetaData
> {
>     setInheritance(InheritanceMetaData inhmd)
>     ...
> }
> and so on.
> We would then require a method on the PMF to register the metadata.
> If there are no objections to such a feature I'll propose a patch to try to provide all current JDO2 capabilities.

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

    [ https://issues.apache.org/jira/browse/JDO-615?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12652884#action_12652884 ]

Craig Russell commented on JDO-615:
-----------------------------------

> Maybe best to just skip the whole services thing for JDOMetaData. Just add the following to the PMF (and JDOEnhancer)
>
> JDOMetadata newMetadata()
> void registerMetadata(JDOMetadata)

Cool.

When adding metadata to PMF and enhancer, what override rules do we want? That is, we need to take a look at this part of Chapter 18:

 JDO 2.2 218 October 10, 2008
When metadata information is needed for a class, and the metadata for that class has not already
been loaded, the metadata is searched for as follows: META-INF/package.jdo, WEB-INF/pack-
age.jdo, package.jdo, <package>/.../<package>/package.jdo, and <package>/<class>.jdo. Once
metadata for a class has been loaded, the metadata will not be replaced in memory as long as the
class is not garbage collected. Therefore, metadata contained higher in the search order will always
be used instead of metadata contained lower in the search order.

So where in this hierarchy does metadata added via calls (I assume that you can make many calls to registerMetadata) go?

> MetaData specification API
> --------------------------
>
>                 Key: JDO-615
>                 URL: https://issues.apache.org/jira/browse/JDO-615
>             Project: JDO
>          Issue Type: New Feature
>            Reporter: Andy Jefferson
>             Fix For: JDO 2 maintenance release 3
>
>         Attachments: jdometadata-4.patch
>
>
> We can specify MetaData via XML or annotations. The only way missing is via an API. I propose mirroring the XML structure with interfaces of the form
> public interface MetaData
> {
>     addExtension(String key, String value);
>     removeExtension(String key, String value);
>     ...
> }
> public interface FileMetaData
> {
>     addPackage(PackageMetaData pmd);
>     ...
> }
> public interface PackageMetaData
> {
>     addClass(ClassMetaData cmd)
>     ...
> }
> public interface ClassMetaData
> {
>     addField(FieldMetaData fmd)
>     ...
> }
> public interface FieldMetaData
> {
>     setInheritance(InheritanceMetaData inhmd)
>     ...
> }
> and so on.
> We would then require a method on the PMF to register the metadata.
> If there are no objections to such a feature I'll propose a patch to try to provide all current JDO2 capabilities.

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

     [ https://issues.apache.org/jira/browse/JDO-615?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Andy Jefferson updated JDO-615:
-------------------------------

    Attachment: jdometadata-5.patch

Updated patch with namings, moved methods from MetadataManager to PersistenceManagerFactory, and add more missing relations in metadata tree.


Re: priority of user-defined metadata.
Why not make user-defined metadata highest priority? That way the user has a way of overriding some package.jdo in the CLASSPATH which they can treat as their fallback. Any problems with this approach that you can see?


Other item : do we want to provide access to metadata for a class being used by the persistence process ? I'd favour something simple like
ClassMetadata pmf.getMetadata(String classname);
This will allow applications to access mapping info (e.g table used for a class) and utilise it in a different part of their app. Obviously it would be down to individual implementations whether they support any subsequent changes to that metadata if handed out to the user.

> MetaData specification API
> --------------------------
>
>                 Key: JDO-615
>                 URL: https://issues.apache.org/jira/browse/JDO-615
>             Project: JDO
>          Issue Type: New Feature
>            Reporter: Andy Jefferson
>             Fix For: JDO 2 maintenance release 3
>
>         Attachments: jdometadata-5.patch
>
>
> We can specify MetaData via XML or annotations. The only way missing is via an API. I propose mirroring the XML structure with interfaces of the form
> public interface MetaData
> {
>     addExtension(String key, String value);
>     removeExtension(String key, String value);
>     ...
> }
> public interface FileMetaData
> {
>     addPackage(PackageMetaData pmd);
>     ...
> }
> public interface PackageMetaData
> {
>     addClass(ClassMetaData cmd)
>     ...
> }
> public interface ClassMetaData
> {
>     addField(FieldMetaData fmd)
>     ...
> }
> public interface FieldMetaData
> {
>     setInheritance(InheritanceMetaData inhmd)
>     ...
> }
> and so on.
> We would then require a method on the PMF to register the metadata.
> If there are no objections to such a feature I'll propose a patch to try to provide all current JDO2 capabilities.

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

     [ https://issues.apache.org/jira/browse/JDO-615?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Andy Jefferson updated JDO-615:
-------------------------------

    Attachment:     (was: jdometadata-4.patch)

> MetaData specification API
> --------------------------
>
>                 Key: JDO-615
>                 URL: https://issues.apache.org/jira/browse/JDO-615
>             Project: JDO
>          Issue Type: New Feature
>            Reporter: Andy Jefferson
>             Fix For: JDO 2 maintenance release 3
>
>         Attachments: jdometadata-5.patch
>
>
> We can specify MetaData via XML or annotations. The only way missing is via an API. I propose mirroring the XML structure with interfaces of the form
> public interface MetaData
> {
>     addExtension(String key, String value);
>     removeExtension(String key, String value);
>     ...
> }
> public interface FileMetaData
> {
>     addPackage(PackageMetaData pmd);
>     ...
> }
> public interface PackageMetaData
> {
>     addClass(ClassMetaData cmd)
>     ...
> }
> public interface ClassMetaData
> {
>     addField(FieldMetaData fmd)
>     ...
> }
> public interface FieldMetaData
> {
>     setInheritance(InheritanceMetaData inhmd)
>     ...
> }
> and so on.
> We would then require a method on the PMF to register the metadata.
> If there are no objections to such a feature I'll propose a patch to try to provide all current JDO2 capabilities.

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

    [ https://issues.apache.org/jira/browse/JDO-615?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12653493#action_12653493 ]

Craig Russell commented on JDO-615:
-----------------------------------

> Re: priority of user-defined metadata.
> Why not make user-defined metadata highest priority? That way the user has a way of overriding some package.jdo in the CLASSPATH which they can treat as their fallback.

The rationale for the algorithm used today is that once metadata has been defined, there may be other metadata that depends on it (e.g. inheritance and relationships). So if you change this you are in danger of breaking things that are working for other parts of the application. I don't have a use-case for changing metadata that's already been defined. Do you?

> Other item : do we want to provide access to metadata for a class being used by the persistence process ? I'd favour something simple like ClassMetadata pmf.getMetadata(String classname);
> This will allow applications to access mapping info (e.g table used for a class) and utilise it in a different part of their app. Obviously it would be down to individual implementations whether they support any subsequent changes to that metadata if handed out to the user.

There are two questions: do we support a way for an application to get the current definition of metadata? I'd say yes.

Do we support changing metadata by modifying the metadata objects that are given to the application? Without a clear understanding of the use-case for this (see above) I'd say no thanks. The metadata instances should be immutable if given out, or at least give out a copy of what's defined, that by definition doesn't change the current copy. Seems like it's "easy enough" to copy metadata.

Yet another more topic: security. We probably need to add a security bit to the registerMetadata and getMetadata calls. We already have the getMetadata permission but might want a setMetadata permission as well.

> MetaData specification API
> --------------------------
>
>                 Key: JDO-615
>                 URL: https://issues.apache.org/jira/browse/JDO-615
>             Project: JDO
>          Issue Type: New Feature
>            Reporter: Andy Jefferson
>             Fix For: JDO 2 maintenance release 3
>
>         Attachments: jdometadata-5.patch
>
>
> We can specify MetaData via XML or annotations. The only way missing is via an API. I propose mirroring the XML structure with interfaces of the form
> public interface MetaData
> {
>     addExtension(String key, String value);
>     removeExtension(String key, String value);
>     ...
> }
> public interface FileMetaData
> {
>     addPackage(PackageMetaData pmd);
>     ...
> }
> public interface PackageMetaData
> {
>     addClass(ClassMetaData cmd)
>     ...
> }
> public interface ClassMetaData
> {
>     addField(FieldMetaData fmd)
>     ...
> }
> public interface FieldMetaData
> {
>     setInheritance(InheritanceMetaData inhmd)
>     ...
> }
> and so on.
> We would then require a method on the PMF to register the metadata.
> If there are no objections to such a feature I'll propose a patch to try to provide all current JDO2 capabilities.

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

    [ https://issues.apache.org/jira/browse/JDO-615?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12653523#action_12653523 ]

Craig Russell commented on JDO-615:
-----------------------------------

Yet more random comments on patch 5:

InterfaceMetadata extends both Metadata and ComponentMetadata. But ComponentMetadata already extends Metadata...

ComponentMetadata might include get/setPersistenceModifier since presumably this applies to interfaces as well. That leaves only FieldMetadata for ClassMetadata which seems correct.

There are several cases of setXXX that take non-enum, non-primitive values. I'd like to eliminate them entirely to avoid user error (reusing metadata elements in multiple places). Can each of these cases be justified? Or can we add factory methods to the interfaces instead (e.g. newVersionMetadata instead of setVersionMetadata)? Then there's no need for setParent either.

ComponentMetadata:
setVersionMetadata
setVersionMetadata
setDatastoreIdentityMetadata
setPrimaryKeyMetadata

DiscriminatorMetadata:
setIndexMetadata

ElementMetadata:
setEmbeddedMetadata
setIndexMetadata
setUniqueMetadata
setForeignKeyMetadata

JoinMetadata:
setForeignKeyMetadata
setPrimaryKeyMetadata

KeyMetadata:
setEmbeddedMetadata
setIndexMetadata
setUniqueMetadata
setForeignKeyMetadata

MemberMetadata:
setArrayMetadata
setCollectionMetadata
setMapMetadata
setJoinMetadata
setEmbeddedMetadata
setElementMetadata
setKeyMetadata
setValueMetadata
setIndexMetadata
setUniqueMetadata
setForeignKeyMetadata

Metadata:
setParent

OrderMetadata:
setIndexMetadata

ValueMetadata:
setEmbeddedMetadata
setIndexMetadata
setUniqueMetadata
setForeignKeyMetadata

VersionMetadata:
setIndexMetadata

In SequenceMetadata, not sure if you intended this to be Class or String... None of the other metadata calls use Class.
+     * Method to set the result class name for the query
+     *
+     * @param cls Result class name
+     */
+    void setFactoryClass(Class cls);

> MetaData specification API
> --------------------------
>
>                 Key: JDO-615
>                 URL: https://issues.apache.org/jira/browse/JDO-615
>             Project: JDO
>          Issue Type: New Feature
>            Reporter: Andy Jefferson
>             Fix For: JDO 2 maintenance release 3
>
>         Attachments: jdometadata-5.patch
>
>
> We can specify MetaData via XML or annotations. The only way missing is via an API. I propose mirroring the XML structure with interfaces of the form
> public interface MetaData
> {
>     addExtension(String key, String value);
>     removeExtension(String key, String value);
>     ...
> }
> public interface FileMetaData
> {
>     addPackage(PackageMetaData pmd);
>     ...
> }
> public interface PackageMetaData
> {
>     addClass(ClassMetaData cmd)
>     ...
> }
> public interface ClassMetaData
> {
>     addField(FieldMetaData fmd)
>     ...
> }
> public interface FieldMetaData
> {
>     setInheritance(InheritanceMetaData inhmd)
>     ...
> }
> and so on.
> We would then require a method on the PMF to register the metadata.
> If there are no objections to such a feature I'll propose a patch to try to provide all current JDO2 capabilities.

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

    [ https://issues.apache.org/jira/browse/JDO-615?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12653699#action_12653699 ]

Andy Jefferson commented on JDO-615:
------------------------------------

> InterfaceMetadata extends both Metadata and ComponentMetadata. But

Good catch.

> ComponentMetadata might include get/setPersistenceModifier since presumably this applies to interfaces as well.

Not in the DTD it doesn't. Not sure what a "persistence-aware" persistent interface would be :-S

> There are several cases of setXXX that take [...] Then there's no need for setParent either.

setParent was a hangover from before adding the newXXX, and can go.
setXXX used to distinguish the single-valued child components from multiple-valued child components (newXXX); naming issue. Since some are single-valued I used setXXX since more like a bean property.

> SequenceMetaData

Yes, inconsistent.



Re: priority order.

My use-case that originated this is for classes where there is no file-based metadata. Consequently I've no problem with the wording being around that, so a user can define metadata for a class that has no existing metadata. As a result, a call to pmf.registerMetadata() with something that tries to redefine a class that already has registered metadata would result in a JDOUserException.

> MetaData specification API
> --------------------------
>
>                 Key: JDO-615
>                 URL: https://issues.apache.org/jira/browse/JDO-615
>             Project: JDO
>          Issue Type: New Feature
>            Reporter: Andy Jefferson
>             Fix For: JDO 2 maintenance release 3
>
>         Attachments: jdometadata-5.patch
>
>
> We can specify MetaData via XML or annotations. The only way missing is via an API. I propose mirroring the XML structure with interfaces of the form
> public interface MetaData
> {
>     addExtension(String key, String value);
>     removeExtension(String key, String value);
>     ...
> }
> public interface FileMetaData
> {
>     addPackage(PackageMetaData pmd);
>     ...
> }
> public interface PackageMetaData
> {
>     addClass(ClassMetaData cmd)
>     ...
> }
> public interface ClassMetaData
> {
>     addField(FieldMetaData fmd)
>     ...
> }
> public interface FieldMetaData
> {
>     setInheritance(InheritanceMetaData inhmd)
>     ...
> }
> and so on.
> We would then require a method on the PMF to register the metadata.
> If there are no objections to such a feature I'll propose a patch to try to provide all current JDO2 capabilities.

--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.