JDO 2.1 specification draft can be reviewed...

[Craig L Russell]

at http://db.apache.org/jdo/documentation.html

Check it out, and send comments...

Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:Craig.Russell@...
P.S. A good JDO? O, Gasp!

[Michelle Caisse]

Hi Craig,

Chapter 19 says: "If xml metadata is defined for annotated classes,
fields, or properties, xml metadata overrides the annotation." I think
there needs to be further discussion about what level the override
happens on. Are all of the annotations in the class automatically
overriden if there is xml for the class, does the override happen only
for annotations for which there is a corresponding xml element, ...?

-- Michelle

Craig L Russell wrote:

> at http://db.apache.org/jdo/documentation.html
>
> Check it out, and send comments...
>
> Craig Russell
> Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
> 408 276-5638 mailto:Craig.Russell@...
> P.S. A good JDO? O, Gasp!
>

[cbeams]

Good question, Michelle.  My first interpretation when reading that  
paragraph is that it would be your latter option, where XML can be  
'mixed in' with annotations, overriding any that already exist on an  
individual basis.  As a user, I would expect this.  It is especially  
important when considering separating out ORM-specific metadata into  
XML.  For example, I would want to be able to specify *what* is  
persistent in annotations, and *how*/*where* it is persisted in XML.

Speaking from my current experience with using 2.1 annotations in a  
large code base, we're putting everything, including ORM metadata in  
annotations.  This is largely to keep things simple.  It's much  
easier for the uninitiated to deal with all the metadata being in  
annotations in the classes they care about than having to know about,  
track down, and understand the package.jdo XML.   However, I can see  
a day coming when we will need to deploy all or part of the code base  
against multiple, somewhat differing data models, and it would be  
nice to be able to override the hard-coded ORM annotations in XML.  
Hopefully that doesn't make for an implementation nightmare :-)

At any rate, thanks for bringing this up.  It'll be nice to have the  
spec be particular on this topic, one way or the other.

- Chris Beams


On Aug 4, 2007, at 2:02 PM, Michelle Caisse wrote:

> Hi Craig,
>
> Chapter 19 says: "If xml metadata is defined for annotated classes,  
> fields, or properties, xml metadata overrides the annotation." I  
> think there needs to be further discussion about what level the  
> override happens on. Are all of the annotations in the class  
> automatically overriden if there is xml for the class, does the  
> override happen only for annotations for which there is a  
> corresponding xml element, ...?
>
> -- Michelle
>
> Craig L Russell wrote:
>
>> at http://db.apache.org/jdo/documentation.html
>>
>> Check it out, and send comments...
>>
>> Craig Russell
>> Architect, Sun Java Enterprise System http://java.sun.com/products/ 
>> jdo
>> 408 276-5638 mailto:Craig.Russell@...
>> P.S. A good JDO? O, Gasp!
>>
>

[cbeams]

Craig,

The introduction's preamble reads:

> Currently, aside from JDO, there are three Java standards for  
> storing Java data persistently: serial-
> ization, JDBC, and Enterprise JavaBeans. Serialization preserves  
> relationships among a graph of
> Java objects, but does not support sharing among multiple users.  
> JDBC requires the user to explic-
> itly manage the values of fields and map them into relational  
> database tables. Enterprise JavaBeans
> require a container in which to run.

There's no mention of JPA here; I imagine there should be, as it is  
indeed a fourth standard.  Perhaps it's out of scope or  
inappropriate, but it would be nice to see the spec 'officially'  
address the relationship between these two increasingly similar  
standards.

Thanks,

- Chris Beams

> From: Craig L Russell <Craig.Russell@...>
> Date: August 3, 2007 7:04:52 PM PDT
> To: Apache JDO project <jdo-dev@...>, JDO Expert Group  
> <jdo-experts-ext@...>
> Subject: JDO 2.1 specification draft can be reviewed...
>
>
> at http://db.apache.org/jdo/documentation.html
>
> Check it out, and send comments...
>
> Craig Russell
> Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
> 408 276-5638 mailto:Craig.Russell@...
> P.S. A good JDO? O, Gasp!
>

[cbeams]

Not to belabor the point here, but reading on I see the following in  
section 2.2 ("Rationale"):

> There is no existing Java platform specification that proposes a  
> standard architecture for storing the
> state of Java objects persistently in transactional datastores.

Not exactly the case anymore.  I suggest this passage be updated (or  
eliminated) in light of JPA.  Perhaps the statement could be amended  
to point out that there is no existing spec that proposes a  
*datastore-agnostic* standard architecture for persistence.  This is  
probably the chief conceptual discriminator between JDO and JPA  
today.  No flame bait intended on this thread, btw; I'm a JDO user  
and advocate.  I mention these things because I believe it's in JDO's  
best interest to acknowledge JPA wherever appropriate, and  
distinguish itself and it's raison d'être wherever it can.

- Chris

On Aug 4, 2007, at 3:49 PM, cbeams wrote:

>
> Craig,
>
> The introduction's preamble reads:
>
>> Currently, aside from JDO, there are three Java standards for  
>> storing Java data persistently: serial-
>> ization, JDBC, and Enterprise JavaBeans. Serialization preserves  
>> relationships among a graph of
>> Java objects, but does not support sharing among multiple users.  
>> JDBC requires the user to explic-
>> itly manage the values of fields and map them into relational  
>> database tables. Enterprise JavaBeans
>> require a container in which to run.
>
> There's no mention of JPA here; I imagine there should be, as it is  
> indeed a fourth standard.  Perhaps it's out of scope or  
> inappropriate, but it would be nice to see the spec 'officially'  
> address the relationship between these two increasingly similar  
> standards.
>
> Thanks,
>
> - Chris Beams
>
>
>> From: Craig L Russell <Craig.Russell@...>
>> Date: August 3, 2007 7:04:52 PM PDT
>> To: Apache JDO project <jdo-dev@...>, JDO Expert Group  
>> <jdo-experts-ext@...>
>> Subject: JDO 2.1 specification draft can be reviewed...
>>
>>
>> at http://db.apache.org/jdo/documentation.html
>>
>> Check it out, and send comments...
>>
>> Craig Russell
>> Architect, Sun Java Enterprise System http://java.sun.com/products/ 
>> jdo
>> 408 276-5638 mailto:Craig.Russell@...
>> P.S. A good JDO? O, Gasp!
>>
>

[cbeams]

Craig, all,

This isn't so much a comment on the 2.1 spec changes, but rather a  
suggestion for an addition to the JDOHelper interface in the 2.1  
timeline (I don't know if it's too late for this sort of thing)...

JPOX's JPOXJDOHelper implementation exposes a very useful method with  
the following signature:

        String getObjectState(Object pc)

I would love to see this method exposed by the standard JDOHelper  
interface.  The spec currently provides status interrogation methods  
(per section 8.5), but they're primarily useful assuming one is  
testing for a particular state.  For example, I might care to assert  
that a pc is 'detached-dirty':

        assert pc.isDetached() && pc.isDirty();

That's not so bad; it's even elegant.   But if I'm debugging my way  
through an application, there's no standardized way (that I know of)  
to simply print out the state of the pc object.  Using JPOX  
internals, I can do the following:

        logger.debug(JPOXJDOHelper.getObjectState(pc));  // prints out  
'detached-dirty', 'transient-clean', or whatever the state actually is.

or, just as easily:

        assert "detached-dirty".equals(JPOXJDOHelper.getObjectState(pc));

This method is most useful from a practical point of view:  
debugging.  One might argue that such code need not be portable and  
thus standardized, but I'd counter with "why not"?  State transitions  
in JDO are complex enough; if we can make the standard interface for  
interrogation of those states friendlier, all the better.

IMHO, the only problem with the current JPOX getObjectState()  
implementation is that it's string-based.  If this method were to be  
considered for the 2.1 JDOHelper interface, I would suggest that the  
return type be an enumeration that contains identifiers for all the  
object states, optional and required:

        package javax.jdo;
        public interface JDOHelper {
                // ...
                ObjectState getObjectState(Object pc);
        }

Where ObjectState is defined as:

        package javax.jdo;
        public enum ObjectState {
                TRANSIENT,
                TRANSIENT_CLEAN,
                TRANSIENT_DIRTY,
                PERSISTENT_NEW,
                PERSISTENT_NONTRANSACTIONAL,
                PERSISTENT_NONTRANSACTIONAL_DIRTY,
                PERSISTENT_CLEAN,
                PERSISTENT_DIRTY,
                HOLLOW,
                PERSISTENT_DELETED,
                PERSISTENT_NEW_DELETED,
                DETACHED_CLEAN,
                DETACHED_DIRTY;
        }

With this addition in place, the user gets the best of both worlds.  
Asserting for a given state is trivially easy:

        assert JDOHelper.getObjectState(pc) == ObjectState.DETACHED_DIRTY;

And determining object state with no a priori knowledge is simple, too:

        logger.debug(JDOHelper.getObjectState(pc)); // prints out  
"DETACHED_DIRTY"

The ObjectState enum could also override toString() such that it  
transforms the all-caps-and-underscores identifier to the lower-case-
and-dashes format used within the spec,  e.g.: DETACHED_DIRTY.toString
() returns "detached-dirty"


Thanks for considering,

- Chris Beams

> From: Craig L Russell <Craig.Russell@...>
> Date: August 3, 2007 7:04:52 PM PDT
> To: Apache JDO project <jdo-dev@...>, JDO Expert Group  
> <jdo-experts-ext@...>
> Subject: JDO 2.1 specification draft can be reviewed...
>
>
> at http://db.apache.org/jdo/documentation.html
>
> Check it out, and send comments...
>
> Craig Russell
> Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
> 408 276-5638 mailto:Craig.Russell@...
> P.S. A good JDO? O, Gasp!
>

[Craig L Russell]

Hi Chris,

Good catch. I'll update the spec for the next go-around.

Thanks,

Craig

On Aug 4, 2007, at 4:18 PM, cbeams wrote:

> Not to belabor the point here, but reading on I see the following  
> in section 2.2 ("Rationale"):
>
>> There is no existing Java platform specification that proposes a  
>> standard architecture for storing the
>> state of Java objects persistently in transactional datastores.
>
> Not exactly the case anymore.  I suggest this passage be updated  
> (or eliminated) in light of JPA.  Perhaps the statement could be  
> amended to point out that there is no existing spec that proposes a  
> *datastore-agnostic* standard architecture for persistence.  This  
> is probably the chief conceptual discriminator between JDO and JPA  
> today.  No flame bait intended on this thread, btw; I'm a JDO user  
> and advocate.  I mention these things because I believe it's in  
> JDO's best interest to acknowledge JPA wherever appropriate, and  
> distinguish itself and it's raison d'être wherever it can.
>
> - Chris
>
> On Aug 4, 2007, at 3:49 PM, cbeams wrote:
>
>>
>> Craig,
>>
>> The introduction's preamble reads:
>>
>>> Currently, aside from JDO, there are three Java standards for  
>>> storing Java data persistently: serial-
>>> ization, JDBC, and Enterprise JavaBeans. Serialization preserves  
>>> relationships among a graph of
>>> Java objects, but does not support sharing among multiple users.  
>>> JDBC requires the user to explic-
>>> itly manage the values of fields and map them into relational  
>>> database tables. Enterprise JavaBeans
>>> require a container in which to run.
>>
>> There's no mention of JPA here; I imagine there should be, as it  
>> is indeed a fourth standard.  Perhaps it's out of scope or  
>> inappropriate, but it would be nice to see the spec 'officially'  
>> address the relationship between these two increasingly similar  
>> standards.
>>
>> Thanks,
>>
>> - Chris Beams
>>
>>
>>> From: Craig L Russell <Craig.Russell@...>
>>> Date: August 3, 2007 7:04:52 PM PDT
>>> To: Apache JDO project <jdo-dev@...>, JDO Expert Group  
>>> <jdo-experts-ext@...>
>>> Subject: JDO 2.1 specification draft can be reviewed...
>>>
>>>
>>> at http://db.apache.org/jdo/documentation.html
>>>
>>> Check it out, and send comments...
>>>
>>> Craig Russell
>>> Architect, Sun Java Enterprise System http://java.sun.com/ 
>>> products/jdo
>>> 408 276-5638 mailto:Craig.Russell@...
>>> P.S. A good JDO? O, Gasp!
>>>
>>
>

Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:Craig.Russell@...
P.S. A good JDO? O, Gasp!

[Craig L Russell]

Hi Chris,

No, it's not too late for changes to the spec. That's why we've  
released it now, while there is still time to add useful things.

I'd like to see others' reaction to this proposal as well.

Regards,

Craig

On Aug 4, 2007, at 6:14 PM, cbeams wrote:

>
> Craig, all,
>
> This isn't so much a comment on the 2.1 spec changes, but rather a  
> suggestion for an addition to the JDOHelper interface in the 2.1  
> timeline (I don't know if it's too late for this sort of thing)...
>
> JPOX's JPOXJDOHelper implementation exposes a very useful method  
> with the following signature:
>
> String getObjectState(Object pc)
>
> I would love to see this method exposed by the standard JDOHelper  
> interface.  The spec currently provides status interrogation  
> methods (per section 8.5), but they're primarily useful assuming  
> one is testing for a particular state.  For example, I might care  
> to assert that a pc is 'detached-dirty':
>
> assert pc.isDetached() && pc.isDirty();
>
> That's not so bad; it's even elegant.   But if I'm debugging my way  
> through an application, there's no standardized way (that I know  
> of) to simply print out the state of the pc object.  Using JPOX  
> internals, I can do the following:
>
> logger.debug(JPOXJDOHelper.getObjectState(pc));  // prints out  
> 'detached-dirty', 'transient-clean', or whatever the state actually  
> is.
>
> or, just as easily:
>
> assert "detached-dirty".equals(JPOXJDOHelper.getObjectState(pc));
>
> This method is most useful from a practical point of view:  
> debugging.  One might argue that such code need not be portable and  
> thus standardized, but I'd counter with "why not"?  State  
> transitions in JDO are complex enough; if we can make the standard  
> interface for interrogation of those states friendlier, all the  
> better.
>
> IMHO, the only problem with the current JPOX getObjectState()  
> implementation is that it's string-based.  If this method were to  
> be considered for the 2.1 JDOHelper interface, I would suggest that  
> the return type be an enumeration that contains identifiers for all  
> the object states, optional and required:
>
> package javax.jdo;
> public interface JDOHelper {
> // ...
> ObjectState getObjectState(Object pc);
> }
>
> Where ObjectState is defined as:
>
> package javax.jdo;
> public enum ObjectState {
> TRANSIENT,
> TRANSIENT_CLEAN,
> TRANSIENT_DIRTY,
> PERSISTENT_NEW,
> PERSISTENT_NONTRANSACTIONAL,
> PERSISTENT_NONTRANSACTIONAL_DIRTY,
> PERSISTENT_CLEAN,
> PERSISTENT_DIRTY,
> HOLLOW,
> PERSISTENT_DELETED,
> PERSISTENT_NEW_DELETED,
> DETACHED_CLEAN,
> DETACHED_DIRTY;
> }
>
> With this addition in place, the user gets the best of both  
> worlds.  Asserting for a given state is trivially easy:
>
> assert JDOHelper.getObjectState(pc) == ObjectState.DETACHED_DIRTY;
>
> And determining object state with no a priori knowledge is simple,  
> too:
>
> logger.debug(JDOHelper.getObjectState(pc)); // prints out  
> "DETACHED_DIRTY"
>
> The ObjectState enum could also override toString() such that it  
> transforms the all-caps-and-underscores identifier to the lower-
> case-and-dashes format used within the spec,  e.g.:  
> DETACHED_DIRTY.toString() returns "detached-dirty"
>
>
> Thanks for considering,
>
> - Chris Beams
>
>
>
>
>> From: Craig L Russell <Craig.Russell@...>
>> Date: August 3, 2007 7:04:52 PM PDT
>> To: Apache JDO project <jdo-dev@...>, JDO Expert Group  
>> <jdo-experts-ext@...>
>> Subject: JDO 2.1 specification draft can be reviewed...
>>
>>
>> at http://db.apache.org/jdo/documentation.html
>>
>> Check it out, and send comments...
>>
>> Craig Russell
>> Architect, Sun Java Enterprise System http://java.sun.com/products/ 
>> jdo
>> 408 276-5638 mailto:Craig.Russell@...
>> P.S. A good JDO? O, Gasp!
>>
>
>

Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:Craig.Russell@...
P.S. A good JDO? O, Gasp!

[cbeams]

Craig, all

Several suggestions relating to evolving the API in support of Java5  
features:


11.6, "Optional Feature Support":

The current draft specifies the signature

        Collection supportedOptions();

then continues to read

        "This method returns a Collection of String [...]"

This suggests that the signature should be

        Collection<String> supportedOptions();



14.6.1, "Query Execution"

I suggest we eliminate

        Object execute(Object p1);
        Object execute(Object p1, Object p2);
        Object execute(Object p1, Object p2, Object p3);

and deprecate

        Object executeWithArray(Object[] parameters);

in favor of a newly added

        Object execute(Object... parameters);

This new method would seamlessly support any existing calls to the  
three eliminated methods, and is a proper replacement for  
executeWithArray().

This would would leave us with three (non-deprecated) execution  
methods off the Query interface:

        Object execute();
        Object execute(Object... parameters);
        Object executeWithMap(Map parameters);



A slightly more radical approach to this evolution would have us also  
eliminate

        Object execute();

because the new varargs method can by definition support calls  
without arguments,

and deprecate

        Object executeWithMap(Map params);

in favor of a new

        Object execute(Map params);

because Java can disambiguate between calls to execute(Object...  
params) and execute(Map params) just fine.  This is predecated by the  
assumption that it would never be valid to pass a Map instance as a  
first-class query parameter.  That might be a faulty assumption, it  
might also just be confusing.

If all these changes were made, we'd be left with an execution API  
consisting of just two methods:

        Object execute(Object... params);
        Object execute(Map params);


This is, I believe, technically favorable and cleaner, but technical  
considerations are not the only valid ones.  Leaving the no-arg  
execute() might be friendly to folks that don't understand varargs, etc.



14.8, "Deletion by Query":

The rationale used above for paring down Query's execute methods  
could also be applied to Query's deletePersistentAll methods.  It  
would be legal and Java5-ish to eliminate the no-arg  
deletePersistentAll method and reduce the API down to:

        long deletePersistentAll(Object... params);
        long deletePersistentAll(Map params);

...

There's a number of other places in the spec changes like the ones  
mentioned here could be made, but I might be getting ahead of  
myself :-)  I'll await comments before touching on anything else.

Thanks,

- Chris Beams

> From: Craig L Russell <Craig.Russell@...>
> Date: August 3, 2007 7:04:52 PM PDT
> To: Apache JDO project <jdo-dev@...>, JDO Expert Group  
> <jdo-experts-ext@...>
> Subject: JDO 2.1 specification draft can be reviewed...
>
>
> at http://db.apache.org/jdo/documentation.html
>
> Check it out, and send comments...
>
> Craig Russell
> Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
> 408 276-5638 mailto:Craig.Russell@...
> P.S. A good JDO? O, Gasp!
>

[Craig L Russell]

Hi Chris,

Good suggestions. I'll take a closer look and verify which can be  
done without compromising compatibility.

Craig

On Aug 4, 2007, at 8:00 PM, cbeams wrote:

> Craig, all
>
> Several suggestions relating to evolving the API in support of  
> Java5 features:
>
>
> 11.6, "Optional Feature Support":
>
> The current draft specifies the signature
>
> Collection supportedOptions();
>
> then continues to read
>
> "This method returns a Collection of String [...]"
>
> This suggests that the signature should be
>
> Collection<String> supportedOptions();
>
>
>
> 14.6.1, "Query Execution"
>
> I suggest we eliminate
>
> Object execute(Object p1);
> Object execute(Object p1, Object p2);
> Object execute(Object p1, Object p2, Object p3);
>
> and deprecate
>
> Object executeWithArray(Object[] parameters);
>
> in favor of a newly added
>
> Object execute(Object... parameters);
>
> This new method would seamlessly support any existing calls to the  
> three eliminated methods, and is a proper replacement for  
> executeWithArray().
>
> This would would leave us with three (non-deprecated) execution  
> methods off the Query interface:
>
> Object execute();
> Object execute(Object... parameters);
> Object executeWithMap(Map parameters);
>
>
>
> A slightly more radical approach to this evolution would have us  
> also eliminate
>
> Object execute();
>
> because the new varargs method can by definition support calls  
> without arguments,
>
> and deprecate
>
> Object executeWithMap(Map params);
>
> in favor of a new
>
> Object execute(Map params);
>
> because Java can disambiguate between calls to execute(Object...  
> params) and execute(Map params) just fine.  This is predecated by  
> the assumption that it would never be valid to pass a Map instance  
> as a first-class query parameter.  That might be a faulty  
> assumption, it might also just be confusing.
>
> If all these changes were made, we'd be left with an execution API  
> consisting of just two methods:
>
> Object execute(Object... params);
> Object execute(Map params);
>
>
> This is, I believe, technically favorable and cleaner, but  
> technical considerations are not the only valid ones.  Leaving the  
> no-arg execute() might be friendly to folks that don't understand  
> varargs, etc.
>
>
>
> 14.8, "Deletion by Query":
>
> The rationale used above for paring down Query's execute methods  
> could also be applied to Query's deletePersistentAll methods.  It  
> would be legal and Java5-ish to eliminate the no-arg  
> deletePersistentAll method and reduce the API down to:
>
> long deletePersistentAll(Object... params);
> long deletePersistentAll(Map params);
>
> ...
>
> There's a number of other places in the spec changes like the ones  
> mentioned here could be made, but I might be getting ahead of  
> myself :-)  I'll await comments before touching on anything else.
>
> Thanks,
>
> - Chris Beams
>
>
>> From: Craig L Russell <Craig.Russell@...>
>> Date: August 3, 2007 7:04:52 PM PDT
>> To: Apache JDO project <jdo-dev@...>, JDO Expert Group  
>> <jdo-experts-ext@...>
>> Subject: JDO 2.1 specification draft can be reviewed...
>>
>>
>> at http://db.apache.org/jdo/documentation.html
>>
>> Check it out, and send comments...
>>
>> Craig Russell
>> Architect, Sun Java Enterprise System http://java.sun.com/products/ 
>> jdo
>> 408 276-5638 mailto:Craig.Russell@...
>> P.S. A good JDO? O, Gasp!
>>
>
>

Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:Craig.Russell@...
P.S. A good JDO? O, Gasp!

[Andy Jefferson]

Hi,

> I'd like to see others' reaction to this proposal as well.
> > String getObjectState(Object pc)

I clearly think it's a good idea since that's why JPOX has it ;-)
Anything that adds more information to the user domain and more clearly
defines the object states is a good thing.

I agree with the principle of making the return an enum (for the "api21" jar -
obviously can't be like that in the legacy jar since that has to support
1.3+). The only issue is that HOLLOW and P_NONTRANS have the same
combinations of the various "isPersistent", "isTransactional", etc fields and
that is why the JPOX method outputs "hollow / persistent-nontransactional"


--
Andy  (Java Persistent Objects - http://www.jpox.org)

[cbeams]

19.20 specifies @Indexes
19.21 specifies @Indices

They appear to be identical in intent, serving as containers when  
more than @Index annotation is required.  JPOX treats them as the  
same annotation, differing only in name.

It seems redundant and potentially confusing to include both of  
these; I suggest we choose one.

While the dictionary (New Oxford American) treats both 'indexes' and  
'indices' as valid plural forms of 'index', it notes that 'indices'  
is favored "especially in technical contexts".  Perhaps we can let  
that be the deciding vote?

- Chris Beams
 

[Craig L Russell]

Hi Chris,

Where would the confusion be in having both?

Craig

On Aug 5, 2007, at 4:32 AM, cbeams wrote:

> 19.20 specifies @Indexes
> 19.21 specifies @Indices
>
> They appear to be identical in intent, serving as containers when  
> more than @Index annotation is required.  JPOX treats them as the  
> same annotation, differing only in name.
>
> It seems redundant and potentially confusing to include both of  
> these; I suggest we choose one.
>
> While the dictionary (New Oxford American) treats both 'indexes'  
> and 'indices' as valid plural forms of 'index', it notes that  
> 'indices' is favored "especially in technical contexts".  Perhaps  
> we can let that be the deciding vote?
>
> - Chris Beams

Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:Craig.Russell@...
P.S. A good JDO? O, Gasp!

[cbeams]

I can imagine other users doing just what I did: sitting in Eclipse,  
typing @Ind and then autocompleting, seeing the two options and  
wondering "what's the difference?"  He heads over to the JPOX  
annotations page only to find that they are the same, one  
interchangeable for the other.  The user scratches his head for a  
moment, asking himself, "which one do I like better?", "am an  
'Indexes' kind of guy, or an 'Indices' man?"  Perhaps he checks the  
dictionary, like yours truly, to determine proper usage.  He  
determines 'Indices' is clearly superior, and moves on.

Meanwhile, down the hall, his fellow programmer engages in the same  
exercise, ultimately deciding that 'Indexes' is the way to go.

They've both spent some pretty unproductive time and worse, the  
application does the same thing in different ways, all in the name of  
accommodating users' personal spelling preferences.

I suggest that the spec ought to be... specific on such matters.

At any rate, its hardly the end of the world if these both stick  
around, but I brought it up so it's at least a conscious decision for  
the group.  My vote is that we choose one, thus reducing the number  
of things users have to learn and understand.

Thanks!

- Chris

On Aug 5, 2007, at 9:33 AM, Craig L Russell wrote:

> Hi Chris,
>
> Where would the confusion be in having both?
>
> Craig
>
> On Aug 5, 2007, at 4:32 AM, cbeams wrote:
>
>> 19.20 specifies @Indexes
>> 19.21 specifies @Indices
>>
>> They appear to be identical in intent, serving as containers when  
>> more than @Index annotation is required.  JPOX treats them as the  
>> same annotation, differing only in name.
>>
>> It seems redundant and potentially confusing to include both of  
>> these; I suggest we choose one.
>>
>> While the dictionary (New Oxford American) treats both 'indexes'  
>> and 'indices' as valid plural forms of 'index', it notes that  
>> 'indices' is favored "especially in technical contexts".  Perhaps  
>> we can let that be the deciding vote?
>>
>> - Chris Beams
>
> Craig Russell
> Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
> 408 276-5638 mailto:Craig.Russell@...
> P.S. A good JDO? O, Gasp!
>

[Craig L Russell]

Hi Jörg,

I have no issue with your suggestion.

Does anyone object? Like an implementation who would have to actually  
do the work? JPOX?

Craig

On Aug 6, 2007, at 3:57 AM, joerg.von.frantzius@... wrote:

> Hello Craig,
>
> I had a quick look at the draft, and, next to feeling honoured, I  
> was particularly happy to see chapter "12.17 Server Date". Only a  
> few weeks ago I made some bad experience with JPA/Hibernate with  
> the same problem of obtaining the current timestamp from the  
> database, with nanoseconds missing in particular. I'd like to  
> comment that having nanoseconds precision where available is very  
> desirable here.
>
> In my case I have to log some kind of events in the database, and  
> later on I need to deterministically retrieve them sorted by  
> timestamp of their occurrence. It turned out that a precision  
> milliseconds was a problem, because events often occured within the  
> same millisecond, so I ended up retrieving logged events in some  
> arbitrary order that was different from their real order of  
> occurrence.
>
> So I'd suggest something along the lines of the following in that  
> chapter:
>
> "The underlying implementation should return instances of  
> java.sql.Timestamp for databases that support nanosecond-precision  
> of date-time values."
>
> Regards,
> Jörg
>
> Zitat von Craig L Russell <Craig.Russell@...>:
>
>> at http://db.apache.org/jdo/documentation.html
>>
>> Check it out, and send comments...
>>
>> Craig Russell
>> Architect, Sun Java Enterprise System http://java.sun.com/products/ 
>> jdo
>> 408 276-5638 mailto:Craig.Russell@...
>> P.S. A good JDO? O, Gasp!
>
>
>

Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:Craig.Russell@...
P.S. A good JDO? O, Gasp!

[David Ezzio-2]

Andy Jefferson wrote:
> Hi,
>
>> I'd like to see others' reaction to this proposal as well.
>>> String getObjectState(Object pc)
>
> I clearly think it's a good idea since that's why JPOX has it ;-)
> Anything that adds more information to the user domain and more clearly
> defines the object states is a good thing.

+1

>
> I agree with the principle of making the return an enum (for the "api21" jar -
> obviously can't be like that in the legacy jar since that has to support
> 1.3+). The only issue is that HOLLOW and P_NONTRANS have the same
> combinations of the various "isPersistent", "isTransactional", etc fields and
> that is why the JPOX method outputs "hollow / persistent-nontransactional"

Since we have always drawn a distinction, perhaps unwisely, between
hollow and PNT, we'll just have to follow that path.

David

[David Ezzio-2]

cbeams wrote:

> I can imagine other users doing just what I did: sitting in Eclipse,
> typing @Ind and then autocompleting, seeing the two options and
> wondering "what's the difference?"  He heads over to the JPOX
> annotations page only to find that they are the same, one
> interchangeable for the other.  The user scratches his head for a
> moment, asking himself, "which one do I like better?", "am an 'Indexes'
> kind of guy, or an 'Indices' man?"  Perhaps he checks the dictionary,
> like yours truly, to determine proper usage.  He determines 'Indices' is
> clearly superior, and moves on.
>
> Meanwhile, down the hall, his fellow programmer engages in the same
> exercise, ultimately deciding that 'Indexes' is the way to go.
>
> They've both spent some pretty unproductive time and worse, the
> application does the same thing in different ways, all in the name of
> accommodating users' personal spelling preferences.
>
> I suggest that the spec ought to be... specific on such matters.
>
> At any rate, its hardly the end of the world if these both stick around,
> but I brought it up so it's at least a conscious decision for the
> group.  My vote is that we choose one, thus reducing the number of
> things users have to learn and understand.

+1

If you go on the assumption that any developer can give only so much
time to learn a new interface, then the value of easy to learn,
understand, remember, and correctly guesstimate is huge.

>
> Thanks!
>
> - Chris
>
> On Aug 5, 2007, at 9:33 AM, Craig L Russell wrote:
>
>> Hi Chris,
>>
>> Where would the confusion be in having both?
>>
>> Craig
>>
>> On Aug 5, 2007, at 4:32 AM, cbeams wrote:
>>
>>> 19.20 specifies @Indexes
>>> 19.21 specifies @Indices
>>>
>>> They appear to be identical in intent, serving as containers when
>>> more than @Index annotation is required.  JPOX treats them as the
>>> same annotation, differing only in name.
>>>
>>> It seems redundant and potentially confusing to include both of
>>> these; I suggest we choose one.
>>>
>>> While the dictionary (New Oxford American) treats both 'indexes' and
>>> 'indices' as valid plural forms of 'index', it notes that 'indices'
>>> is favored "especially in technical contexts".  Perhaps we can let
>>> that be the deciding vote?
>>>
>>> - Chris Beams
>>
>> Craig Russell
>> Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
>> 408 276-5638 mailto:Craig.Russell@...
>> P.S. A good JDO? O, Gasp!
>>
>
>

Notice:  This email message, together with any attachments, may contain information  of  BEA Systems,  Inc.,  its subsidiaries  and  affiliated entities,  that may be confidential,  proprietary,  copyrighted  and/or legally privileged, and is intended solely for the use of the individual or entity named in this message. If you are not the intended recipient, and have received this message in error, please immediately return this by email and then delete it.

[Craig L Russell]

If there are no other comments in the next day, I'll remove the  
@Indexes annotation.

Craig

On Aug 13, 2007, at 8:33 AM, David Ezzio wrote:

>
>
> cbeams wrote:
>> I can imagine other users doing just what I did: sitting in Eclipse,
>> typing @Ind and then autocompleting, seeing the two options and
>> wondering "what's the difference?"  He heads over to the JPOX
>> annotations page only to find that they are the same, one
>> interchangeable for the other.  The user scratches his head for a
>> moment, asking himself, "which one do I like better?", "am an  
>> 'Indexes'
>> kind of guy, or an 'Indices' man?"  Perhaps he checks the dictionary,
>> like yours truly, to determine proper usage.  He determines  
>> 'Indices' is
>> clearly superior, and moves on.
>>
>> Meanwhile, down the hall, his fellow programmer engages in the same
>> exercise, ultimately deciding that 'Indexes' is the way to go.
>>
>> They've both spent some pretty unproductive time and worse, the
>> application does the same thing in different ways, all in the name of
>> accommodating users' personal spelling preferences.
>>
>> I suggest that the spec ought to be... specific on such matters.
>>
>> At any rate, its hardly the end of the world if these both stick  
>> around,
>> but I brought it up so it's at least a conscious decision for the
>> group.  My vote is that we choose one, thus reducing the number of
>> things users have to learn and understand.
>
> +1
>
> If you go on the assumption that any developer can give only so much
> time to learn a new interface, then the value of easy to learn,
> understand, remember, and correctly guesstimate is huge.
>
>>
>> Thanks!
>>
>> - Chris
>>
>> On Aug 5, 2007, at 9:33 AM, Craig L Russell wrote:
>>
>>> Hi Chris,
>>>
>>> Where would the confusion be in having both?
>>>
>>> Craig
>>>
>>> On Aug 5, 2007, at 4:32 AM, cbeams wrote:
>>>
>>>> 19.20 specifies @Indexes
>>>> 19.21 specifies @Indices
>>>>
>>>> They appear to be identical in intent, serving as containers when
>>>> more than @Index annotation is required.  JPOX treats them as the
>>>> same annotation, differing only in name.
>>>>
>>>> It seems redundant and potentially confusing to include both of
>>>> these; I suggest we choose one.
>>>>
>>>> While the dictionary (New Oxford American) treats both 'indexes'  
>>>> and
>>>> 'indices' as valid plural forms of 'index', it notes that 'indices'
>>>> is favored "especially in technical contexts".  Perhaps we can let
>>>> that be the deciding vote?
>>>>
>>>> - Chris Beams
>>>
>>> Craig Russell
>>> Architect, Sun Java Enterprise System http://java.sun.com/ 
>>> products/jdo
>>> 408 276-5638 mailto:Craig.Russell@...
>>> P.S. A good JDO? O, Gasp!
>>>
>>
>>
>
>
> Notice:  This email message, together with any attachments, may  
> contain information  of  BEA Systems,  Inc.,  its subsidiaries  
> and  affiliated entities,  that may be confidential,  proprietary,  
> copyrighted  and/or legally privileged, and is intended solely for  
> the use of the individual or entity named in this message. If you  
> are not the intended recipient, and have received this message in  
> error, please immediately return this by email and then delete it.

Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:Craig.Russell@...
P.S. A good JDO? O, Gasp!

[Craig L Russell]

Hi Chris,

Corrected in draft dated 2007-09-28. FYI, here's the corrected text:

Currently, aside from JDO, there are four Java standards for storing  
Java data persistently: serialization, JDBC, Enterprise JavaBeans,  
and Java Persistence API. Serialization preserves relationships among  
a graph of Java objects, but does not support sharing among multiple  
users. JDBC requires the user to explicitly manage the values of  
fields and map them into relational database tables. Enterprise  
JavaBeans require a container in which to run. Java Persistence API  
can run either in a container or in a Java SE VM.

Craig

On Aug 4, 2007, at 3:49 PM, cbeams wrote:

>
> Craig,
>
> The introduction's preamble reads:
>
>> Currently, aside from JDO, there are three Java standards for  
>> storing Java data persistently: serial-
>> ization, JDBC, and Enterprise JavaBeans. Serialization preserves  
>> relationships among a graph of
>> Java objects, but does not support sharing among multiple users.  
>> JDBC requires the user to explic-
>> itly manage the values of fields and map them into relational  
>> database tables. Enterprise JavaBeans
>> require a container in which to run.
>
> There's no mention of JPA here; I imagine there should be, as it is  
> indeed a fourth standard.  Perhaps it's out of scope or  
> inappropriate, but it would be nice to see the spec 'officially'  
> address the relationship between these two increasingly similar  
> standards.
>
> Thanks,
>
> - Chris Beams
>
>
>> From: Craig L Russell <Craig.Russell@...>
>> Date: August 3, 2007 7:04:52 PM PDT
>> To: Apache JDO project <jdo-dev@...>, JDO Expert Group  
>> <jdo-experts-ext@...>
>> Subject: JDO 2.1 specification draft can be reviewed...
>>
>>
>> at http://db.apache.org/jdo/documentation.html
>>
>> Check it out, and send comments...
>>
>> Craig Russell
>> Architect, Sun Java Enterprise System http://java.sun.com/products/ 
>> jdo
>> 408 276-5638 mailto:Craig.Russell@...
>> P.S. A good JDO? O, Gasp!
>>
>

Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:Craig.Russell@...
P.S. A good JDO? O, Gasp!

[Craig L Russell]

I've added this to the latest draft of the specification dated  
2007-09-28.

8.6 State Interrogation
public static ObjectState getObjectState(Object pc);
This method returns an enum representing the life cycle state of the  
parameter instance. The enum has an overloaded toString method that  
returns the life cycle state as discussed in section 5.5.
8.6.1 enum ObjectState
public enum ObjectState {
        TRANSIENT("transient"),
        TRANSIENT_CLEAN("transient-clean"),
        TRANSIENT_DIRTY("transient-dirty"),
        PERSISTENT_NEW("persistent-new"),
        HOLLOW_PERSISTENT_NONTRANSACTIONAL("hollow/persistent-
nontransactional"),
        PERSISTENT_NONTRANSACTIONAL_DIRTY("persistent-nontransactional-dirty"),
        PERSISTENT_CLEAN("persistent-clean"),
        PERSISTENT_DIRTY("persistent-dirty"),
        PERSISTENT_DELETED("persistent-deleted"),
        PERSISTENT_NEW_DELETED("persistent-new-deleted"),
        DETACHED_CLEAN("detached-clean"),
        DETACHED_DIRTY("detached-dirty");
}

Craig

On Aug 4, 2007, at 6:14 PM, cbeams wrote:

>
> Craig, all,
>
> This isn't so much a comment on the 2.1 spec changes, but rather a  
> suggestion for an addition to the JDOHelper interface in the 2.1  
> timeline (I don't know if it's too late for this sort of thing)...
>
> JPOX's JPOXJDOHelper implementation exposes a very useful method  
> with the following signature:
>
> String getObjectState(Object pc)
>
> I would love to see this method exposed by the standard JDOHelper  
> interface.  The spec currently provides status interrogation  
> methods (per section 8.5), but they're primarily useful assuming  
> one is testing for a particular state.  For example, I might care  
> to assert that a pc is 'detached-dirty':
>
> assert pc.isDetached() && pc.isDirty();
>
> That's not so bad; it's even elegant.   But if I'm debugging my way  
> through an application, there's no standardized way (that I know  
> of) to simply print out the state of the pc object.  Using JPOX  
> internals, I can do the following:
>
> logger.debug(JPOXJDOHelper.getObjectState(pc));  // prints out  
> 'detached-dirty', 'transient-clean', or whatever the state actually  
> is.
>
> or, just as easily:
>
> assert "detached-dirty".equals(JPOXJDOHelper.getObjectState(pc));
>
> This method is most useful from a practical point of view:  
> debugging.  One might argue that such code need not be portable and  
> thus standardized, but I'd counter with "why not"?  State  
> transitions in JDO are complex enough; if we can make the standard  
> interface for interrogation of those states friendlier, all the  
> better.
>
> IMHO, the only problem with the current JPOX getObjectState()  
> implementation is that it's string-based.  If this method were to  
> be considered for the 2.1 JDOHelper interface, I would suggest that  
> the return type be an enumeration that contains identifiers for all  
> the object states, optional and required:
>
> package javax.jdo;
> public interface JDOHelper {
> // ...
> ObjectState getObjectState(Object pc);
> }
>
> Where ObjectState is defined as:
>
> package javax.jdo;
> public enum ObjectState {
> TRANSIENT,
> TRANSIENT_CLEAN,
> TRANSIENT_DIRTY,
> PERSISTENT_NEW,
> PERSISTENT_NONTRANSACTIONAL,
> PERSISTENT_NONTRANSACTIONAL_DIRTY,
> PERSISTENT_CLEAN,
> PERSISTENT_DIRTY,
> HOLLOW,
> PERSISTENT_DELETED,
> PERSISTENT_NEW_DELETED,
> DETACHED_CLEAN,
> DETACHED_DIRTY;
> }
>
> With this addition in place, the user gets the best of both  
> worlds.  Asserting for a given state is trivially easy:
>
> assert JDOHelper.getObjectState(pc) == ObjectState.DETACHED_DIRTY;
>
> And determining object state with no a priori knowledge is simple,  
> too:
>
> logger.debug(JDOHelper.getObjectState(pc)); // prints out  
> "DETACHED_DIRTY"
>
> The ObjectState enum could also override toString() such that it  
> transforms the all-caps-and-underscores identifier to the lower-
> case-and-dashes format used within the spec,  e.g.:  
> DETACHED_DIRTY.toString() returns "detached-dirty"
>
>
> Thanks for considering,
>
> - Chris Beams
>
>
>
>
>> From: Craig L Russell <Craig.Russell@...>
>> Date: August 3, 2007 7:04:52 PM PDT
>> To: Apache JDO project <jdo-dev@...>, JDO Expert Group  
>> <jdo-experts-ext@...>
>> Subject: JDO 2.1 specification draft can be reviewed...
>>
>>
>> at http://db.apache.org/jdo/documentation.html
>>
>> Check it out, and send comments...
>>
>> Craig Russell
>> Architect, Sun Java Enterprise System http://java.sun.com/products/ 
>> jdo
>> 408 276-5638 mailto:Craig.Russell@...
>> P.S. A good JDO? O, Gasp!
>>
>
>

Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:Craig.Russell@...
P.S. A good JDO? O, Gasp!