SDO Facets and the SDO Java Specification

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

Title: SDO Facets and the SDO Java Specification

Hi Everyone,
Here is a draft for how facets could be reflected in the Java spec.  I spent a few cycles trying to improve the integration with JSR-303, and trying to do without the new @SdoFacets annotations, but I couldn't really find a way to use the JSR annotations together with @SdoDataType.  If anyone has some better ideas, I'm all ears.

The availablity of JSR-303 also has implications for what we require regarding validation.  Since 303 provides a validation framework, I don't think there is any motivation for SDO to standardize another API for deferred validation.  To mix in the new @SdoFacets annotation with JSR-303 requires providing a ConstraintValidator as part of the API.  This could go in the commonj.sdo.impl or commonj.sdo.util package.   If there is approval for the approach, I will provide this code.

In this draft, I do not say anything about fail-fast validation at all.  My argument is that this is anyway an error situation, and we generally we leave the question of error tolerance to the implementations.  Even if we "required" throwing an exception, an implementation could always claim the right to "do better" by handling the error, so the requirement would be meaningless anyway.  

In addition to this text, the definition of @SdoDataType should be enhanced with an "SdoFacets facet() default @SdoFacets();" member.

Here's the text, which goes at the end of the 7th subsection in Chapter 3 of the SDO Java Spec.
____________________________________________________________________________________________________________________________

3.7.9 JSR-303 Annotations

JSR-303 defines a meta-data model and a set of annotations for JavaBean^TM validation, and these annotations can be used as a source of metadata regarding a property’s type.

The mapping between the standard annotations defined in JSR-303 and the standard facets defined in the SDO Core specification is given in the following table:

Javax.validation Annotation     Sub type of Facet       Notes  
@DecimalMin([value])    MinInclusive
    value=[value]       [value] is a numeric string    
@DecimalMax([value])    MaxInclusive
    value=[value]       [value] is a numeric string    
@Min([value])   MinInclusive
    value=”[value]”     [value] is an integer, in the facet it is converted to a String.       
@Max([value])   MaxInclusive
    value=”[value]”     [value] is an integer, in the facet it is converted to a String.       
@Size(min=[minValue],
        max=[maxValue])
        If minValue<maxValue
MinLength
  value=[minValue]
MaxLength
    value=[maxValue]

otherwise

Length
    value=[minValue]    If either [minValue] or [maxValue] has the defaultValue, then the corresponding MinLength or MaxLength facet is not generated.

Interpretaton of @Size on multivalued properties is implementation dependent.  
@Pattern([pattern])     Pattern
    value=[pattern]            
@Digits(fraction=[fDigits],
              integer=[iDigits])        FractionDigits
    value = [fDigits]
TotalDigits
    Value=[iDigits]+[fDigits]   Using JSR-303 annotations, there is no way to specify TotalDigits if fraction digists is left to its default value.    

The effect of the JSR-303 annotations is analogous to the use of anonymous types in XSD.  Client code finds the type of the associated SDO property through Property.getType(); there is no other portable way to retrieve the type.  Property.getType().getBaseTypes() MUST be a list of length 1 and the value of this element MUST be the SDO Type that matches the javaType, according to the table in section 3.3. 

3.7.10 @SdoFacets
The @SdoFacets annotation is a JSR-303 compliant annotation that provides for a mechanism through which facets defined in the SDO Core Specification can be expressed as Java annotations.  Since the annotation is compliant with the JSR and an implementation of the constraint validator is included as part of the API, the @SdoFacet annotation can be used together with any compliant JSR-303 implementation.  There is some overlap of fuctionality with the use of the standard annotations defined in JSR-303.  Which annotations should be used will depend on the use-case.  For instance, if the Java classes are generated from an XSD, an implementation may find it more natural to use the @SdoFacets annotation.  When integrating with a source code that already uses JSR-303 annotations, then these annotations will naturally be used.

The @SdoFacets annotation can be used as a member of the @SdoDataType annotation, in order to define registered data types.  There is no mechanism to provide similar functionality using JSR-303 annotations.

As with the JSR-303 annotations, the effect of using @SdoFacets to annotate a getter method is analogous to the use of anonymous types in XSD.  Client code finds the type of the associated SDO property through Property.getType(); there is no other portable way to retrieve the type.  Property.getType().getBaseTypes() MUST be a list of length 1 and the value of this element MUST be the SDO Type that matches the javaType, according to the table in section 3.3. 

@Constraint(validatedBy={commonj.sdo.impl.facetValidator.class})
@Retention(RetentionPolicy.RUNTIME)
@Target(@Target({ElementType.METHOD,   
ElementType.FIELD,ElementType.ANNOTATION_TYPE})
public @interface SdoFacets {

    String message() default "{constraint.facet}";
    Class<?>[] groups() default { };

    int length() default -1;
    int minLength() default -1;
    int maxLength() default -1;
    String minInclusive() default "";
    String minExclusive() default default "";
    String maxInclusive()default "";
    String maxExclusive()default "";
    int totalDigits() default -1;
    int fractionDigits() default -1;
    String[] enumeration() default {};
    String[] pattern() default {};

}
The mapping between the members of this annotation and the facets defined in the SDO core specification is straightforward.

Core Facet      Java   
Length

   value=[value]
                                        @SdoFacet(length=[value])      
MinLength
   value=[value]        @SdoFacet(minLength=[value])
       
MinLength
   value=[value]        @SdoFacet(maxLength=[value])
       
MinInclusive
   value=[value]        @SdoFacet(minInclusive=[value])
       
MaxInclusive
   value=[value]        @SdoFacet(maxInclusive=[value])
       
MinExclusive
   value=[value]        @SdoFacet(minExclusive=[value])
       
MaxExclusive
   value=[value]        @SdoFacet(maxExclusive=[value])
       
TotalDigits
   value=[value]        @SdoFacet(totalDigits=[value]) 
FractionDigits
   value=[value]        @SdoFacet(fractionDigits=[value])      
Pattern
    value=[value]       @SdoFacet(pattern=[value])     
<xs:emumeration=[option1]/>
<xs:emumeration=[option2]/>
<xs:emumeration=[option3]/>
…

        @SdoFacet(enumeration={[option1],[option2],[option3]…})

Note:  the type of the enumeration facet is an array of strings.