XML Annotations

["Barack, Ron" <ron.barack@sap.com>]

Title: XML Annotations

Hi Everyone,

Before beginning on this weeks action items, I better send out the AI I actually was given last week, which was to send out the annotations we are using to allow the programmer some XML-specific control of the XSD that is generated from his type system.

First, a note on use-cases.  In my opinion, there are 2 main use-cases.

1)  XSD is in the driver seat.  The programmer is given an XSD, and cannot modify the generated type system presumable because there is some web service involved and if the sdo is changed, the SDO serialization will produce XML that is not valid according to the other party's XSD.

2)  SDO is in the driver seat.  The programmer really doesn't care how the XML looks (eg, what's an element and what's an attribute).  If there is a web service involved, I guess we are generating the WSDL based on the XSD produced by XSDHelper.

In neither of these use-cases do we need the annotation described in this mail.  The only case where you need these annotations is where the programmer cares about the details of the XSD, but doesn't really have the XSD fixed.  In my experience, this usually involved being given an XSD to start with, but then being allowed to add some new properties to it.  Like all code generation solutions, things work great in the first iteration, but start breaking down as soon as the code tries to survive the next iteration.  In such cases, I guess the annotations here come in handy.

In our implementation, what we have is an annotation class that looks like this:

@Retention(RetentionPolicy.RUNTIME)
public @interface XmlPropertyMetaData {
        boolean xmlElement() default true;
        String xsdType() default "";
        String xsdName() default "";
    String ref() default "";
}

The meanings are, I hope, clear.  The values that are URI/Name pairs (xsdType and ref) are assumed to be in the standard SDO format, ie, "namespace#localName".

The annotation is not used as a freestanding annotation, but as the value of the SdoPropertyMetadata property… this annotation is described in the other document, and we add to it…

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD ElementType.FIELD)
public @interface SdoPropertyMetaData {
      // other stuff...
        XmlPropertyMetaData xmlInfo() default @XmlPropertyMetaData;
}
 
I suppose XMLPropertyMetaData could also be freestanding, again with properties and fields as the targets of the annotation.

Of course, it's pretty limited in ist expressiveness, but it seems to handle the majority of use-cases, at least in our experience.  If the programmer really wants to express choices, substitution groups, etc, then he should rather be using XSD as the driving language, and going through code generation with each change.

Ron