xml-xmlbeans-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Patrick Calahan <p...@bea.com>
Subject Re: Current start-with-java annotations
Date Mon, 24 Nov 2003 20:54:27 GMT
At 05:36 AM 11/22/2003 -0500, David Bau wrote:
>OK, everybody's favorite topic, organizing annoation names.  Now with JSR
>175, lots of folks are going to be getting into the business...  Here we go.
>
>Comments on
>http://nagoya.apache.org/wiki/apachewiki.cgi?XmlBeansStartWithJavaAnnotations
>
>Some questions:
>
>I've inferred the javadoc syntax from your table in the examples I put at
>the bottom of the wiki page do I have it right?  Do the examples otherwise
>look like what you intended?


Yup, that looks right.


>On attribute naming... Would we ever be allowed to specify both
>@xsdgen:element and @xsdgen:attribute at the same time?  Probably not,
>right?  To eliminate a degree of freedom which would only be an error, it
>seems like these two could be merged into the same annotation (in which case
>is-attribute would be a boolean setting).  There are no "best practices" for
>175 yet, but reducing illusory degrees of freedom seems like a kind of
>principle.  Agree/disagree?

A while back, I noticed this as well brought up the point with Scott.  His 
response is that it makes more sense for the annotations to be named in 
terms of the target domain (schema) rather than the source (java).  I'm was 
actually pretty persuaded by that argument.

A good example of some prior art in this area is ejbgen.  If you look at 
the tags the Cedric came up with

http://www.beust.com/cedric/ejbgen/#tags-documentation

you will notice that there are many cases where he faces exactly the same 
dilemma in several places (e.g. cmp-field and cmr-field), and that he went 
the route of having separate annotation types.

As I see it, the downsides of this approach are
   1) as you point out, you may have to introduce some arbitrary rules like 
"only one of these annotations must appear."
   2) you may get some redundancy when annotation types are similar

However, the upsides are:
   3) You don't have arbitrary rules like "isNillable can only be specified 
if isAttribute is true."  With the ejbgen-style annotations, you will 
actually get compile-time checking under 175 for this kind of correctness, 
because these sorts of constraints are expressed in the annotation types 
themselves.
   4) More readability and clarity about how java constructs are mapping 
into the schema.

IMHO, #3 outweighs #1, and #2 and #4 are at worst a wash.


>On the opposite side, complexType.rootElement feels like a weird name, since
>schema elements are not types (and this is a source of common source of
>confusion we should work to reduce), and a generated element definition is
>independent of its complex type definition.  Should we consider splitting
>complexType and globalElement into separate annotations?

Right, good point.  That does seems like the right thing to do.

However, I can anticipate one catch with 175, which is that you are only 
able to specify one annotation of a given annotation type for a given java 
construct.  So if we had a separate rootElement annotation type, we would 
only be able to map a class to a single root element.  The way around this 
would be a container type (rootElements) that has a single property, an 
array of rootElement annotations.  That feels a little clunky, though.  The 
alternative would be to hang an array of rootElements on complexType, but 
that doesn't resolve the weirdness you point out.


>Also, you have the ability to specify the rootElement localname, but not the
>targetNamespace, which is 1/2 of the degrees of freedom available for the
>global element definition name.  Would element targetNamespace be added as a
>knob in the future?

Sure.


>For my edification, how should targetNamespace be chosen by default?  Is it
>based on the package name, or is it a global setting on the command-line of
>the java->schema compiler?

Yeah, currently, it will just synthesize a namespace from the package if 
there is no tns annotation.  However, I think it will be useful to allow 
users to give users a package-level annotation (which are formally 
supported in 175) to provide the tns for all of the classes in a package, 
or a command-line switch like you mention (which in some sense is a global 
annotation).  Most local scoping wins in the case of multiple tns 
annotations.  A tns would synthesized only in the absence of any tns 
annotations.

Does that make sense?


>Finally, a couple details - you have element.exclude as a "present/absent"
>kind of switch.  I think 175 is going to give us defaults, but when a
>property is present, you'll have to specify a value, so seems like it should

Right, this is actually a fairly interesting question.  175 actually does 
include the notion of an empty marker annotation, which would allow you to 
do something like this:

@interface Exclude {}
@interface ComplexType { String name(); }
public interface MyInterface {
   @Exclude
   @ComplexType(name="foobie")
   public String getFoo();
}

However, AFAICT, there is not really a nice way to use this when the marker 
is a member of a complex annotation, e.g. you would have to do something like:

@interface Exclude {}
@interface ComplexType {
   Exclude exclude();
   String name();
}
public interface MyInterface {
   @ComplexType(name="foobie",exclude=@Exclude)
   public String getFoo();
}

Wish is not very nice.  I will send an email to the 175 guys - it would be 
nice to be able to just say 'exclude' instead of 'exclude=@Exclude'.

So, I guess the question is - do we want 'exclude' to be a member of the 
ComplexType annotation, or should it be a separate type altogether (as in 
the first example)?

In some ways, I think having a separate Exclude annotation makes more 
sense.  For one thing, it's much more compact.  More importantly, though, 
there isn't really much point in declaring the ComplexType annotation if 
it's going to be excluded anyway.  This will be especially true if we ever 
had a required property on an annotation type - you would have to specify a 
dummy value even if exclude were true.


>be a boolean with a default of "false"?  Similarly, you've listed nillable
>as an NCName rather than a boolean - seems like a typo?

Right, just fixed it.

-p






>David
>
>
>- ---------------------------------------------------------------------
>To unsubscribe, e-mail:   xmlbeans-dev-unsubscribe@xml.apache.org
>For additional commands, e-mail: xmlbeans-dev-help@xml.apache.org
>Apache XMLBeans Project -- URL: http://xml.apache.org/xmlbeans/

Mime
View raw message