#458: update orm schema for 3.2

[lukasj]

see #458

@gavinking review this one carefully - I have also added few missing things from the past (mostly related to foreign-key added in 2.1)

diff -ub orm_3_1.xsd orm_3_2.xsd

``` --- orm_3_1.xsd 2023-10-27 22:59:49 +++ orm_3_2.xsd 2023-10-27 23:05:22 @@ -1,6 +1,6 @@ + + + + + @Target({}) @Retention(RUNTIME) + public @interface CheckConstraint { + String name() default ""; + String constraint(); + String options() default ""; + } + + + + + + + + + + @@ -471,8 +492,10 @@ String catalog() default ""; String schema() default ""; JoinColumn[] joinColumns() default {}; + ForeignKey foreignKey() default @ForeignKey(ConstraintMode.PROVIDER_DEFAULT); UniqueConstraint[] uniqueConstraints() default {}; Index[] indexes() default {}; + String options() default ""; } @@ -492,6 +515,7 @@ + @@ -509,39 +533,48 @@ boolean insertable() default true; boolean updatable() default true; String columnDefinition() default ""; + String options() default ""; String table() default ""; int length() default 255; int precision() default 0; // decimal precision int scale() default 0; // decimal scale + CheckConstraint[] check() default {}; + String comment() default ""; } + + + + + - + type() default void.class; } - + ]]> @@ -553,7 +586,7 @@ - public enum ConstraintMode {CONSTRAINT, NO_CONSTRAINT, PROVIDER_DEFAULT}; + public enum ConstraintMode { CONSTRAINT, NO_CONSTRAINT, PROVIDER_DEFAULT } @@ -569,15 +602,15 @@ - + targetClass(); ColumnResult[] columns(); } - + ]]> - + converter() default AttributeConverter.class; String attributeName() default ""; boolean disableConversion() default false; } - + ]]> @@ -615,7 +649,7 @@ - @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) + @Target({TYPE}) @Retention(RUNTIME) public @interface Converter { boolean autoApply() default false; } @@ -640,6 +674,7 @@ String name() default "DTYPE"; DiscriminatorType discriminatorType() default STRING; String columnDefinition() default ""; + String options() default ""; int length() default 31; } @@ -648,6 +683,7 @@ + @@ -657,7 +693,7 @@ - public enum DiscriminatorType { STRING, CHAR, INTEGER }; + public enum DiscriminatorType { STRING, CHAR, INTEGER } @@ -688,15 +724,15 @@ - + targetClass() default void.class; + FetchType fetch() default FetchType.LAZY; } - + ]]> @@ -899,14 +935,14 @@ - + [] value(); } - + ]]> - + entityClass(); + LockModeType lockMode() default LockModeType.OPTIMISTIC; FieldResult[] fields() default {}; String discriminatorColumn() default ""; } - + ]]> + @@ -943,10 +981,7 @@ - public enum EnumType { - ORDINAL, - STRING - } + public enum EnumType { ORDINAL, STRING } @@ -978,7 +1013,7 @@ - public enum FetchType { LAZY, EAGER }; + public enum FetchType { LAZY, EAGER } @@ -1017,12 +1052,12 @@ String name() default ""; ConstraintMode value() default CONSTRAINT; String foreign-key-definition() default ""; + String options() default ""; + } Note that the elements that embed the use of the annotation default this use as @ForeignKey(PROVIDER_DEFAULT). - } - @@ -1031,6 +1066,7 @@ + @@ -1057,7 +1093,7 @@ - public enum GenerationType { TABLE, SEQUENCE, IDENTITY, UUID, AUTO }; + public enum GenerationType { TABLE, SEQUENCE, IDENTITY, UUID, AUTO } @@ -1101,14 +1137,14 @@ - + value(); } - + ]]> @@ -1124,6 +1160,7 @@ String name() default ""; String columnList(); boolean unique() default false; + String options() default ""; } @@ -1134,6 +1171,7 @@ + @@ -1144,7 +1182,7 @@ @Target({TYPE}) @Retention(RUNTIME) public @interface Inheritance { - InheritanceType strategy() default SINGLE_TABLE; + InheritanceType strategy() default InheritanceType.SINGLE_TABLE; } @@ -1158,8 +1196,7 @@ - public enum InheritanceType - { SINGLE_TABLE, JOINED, TABLE_PER_CLASS}; + public enum InheritanceType { SINGLE_TABLE, TABLE_PER_CLASS, JOINED } @@ -1176,6 +1213,7 @@ + @Repeatable(JoinColumns.class) @Target({METHOD, FIELD}) @Retention(RUNTIME) public @interface JoinColumn { String name() default ""; @@ -1185,12 +1223,21 @@ boolean insertable() default true; boolean updatable() default true; String columnDefinition() default ""; + String options() default ""; String table() default ""; ForeignKey foreignKey() default @ForeignKey(); + CheckConstraint[] check() default {}; + String comment() default ""; } + + + + @@ -1198,7 +1245,9 @@ + + @@ -1214,8 +1263,13 @@ String schema() default ""; JoinColumn[] joinColumns() default {}; JoinColumn[] inverseJoinColumns() default {}; + ForeignKey foreignKey() default @ForeignKey(ConstraintMode.PROVIDER_DEFAULT); + ForeignKey inverseForeignKey() default @ForeignKey(ConstraintMode.PROVIDER_DEFAULT); UniqueConstraint[] uniqueConstraints() default {}; Index[] indexes() default {}; + CheckConstraint[] check() default {}; + String comment() default ""; + String options() default ""; } @@ -1237,10 +1291,14 @@ minOccurs="0" maxOccurs="unbounded"/> + + + @@ -1262,7 +1320,7 @@ - public enum LockModeType { READ, WRITE, OPTIMISTIC, OPTIMISTIC_FORCE_INCREMENT, PESSIMISTIC_READ, PESSIMISTIC_WRITE, PESSIMISTIC_FORCE_INCREMENT, NONE}; + public enum LockModeType implements FindOption, RefreshOption { READ, WRITE, OPTIMISTIC, OPTIMISTIC_FORCE_INCREMENT, PESSIMISTIC_READ, PESSIMISTIC_WRITE, PESSIMISTIC_FORCE_INCREMENT, NONE} @@ -1283,17 +1341,17 @@ - + targetEntity() default void.class; CascadeType[] cascade() default {}; - FetchType fetch() default LAZY; + FetchType fetch() default FetchType.LAZY; String mappedBy() default ""; } - + ]]> @@ -1353,17 +1411,17 @@ - + targetEntity() default void.class; CascadeType[] cascade() default {}; - FetchType fetch() default EAGER; + FetchType fetch() default FetchType.EAGER; boolean optional() default true; } - + ]]> @@ -1408,14 +1466,14 @@ - + value(); } - + ]]> @@ -1434,6 +1492,7 @@ boolean insertable() default true; boolean updatable() default true; String columnDefinition() default ""; + String options() default ""; String table() default ""; int length() default 255; int precision() default 0; // decimal precision @@ -1448,6 +1507,7 @@ + @@ -1460,6 +1520,7 @@ + @Repeatable(MapKeyJoinColumns.class) @Target({METHOD, FIELD}) @Retention(RUNTIME) public @interface MapKeyJoinColumn { String name() default ""; @@ -1469,11 +1530,17 @@ boolean insertable() default true; boolean updatable() default true; String columnDefinition() default ""; + String options() default ""; String table() default ""; + ForeignKey foreignKey() default @ForeignKey(ConstraintMode.PROVIDER_DEFAULT); } + + + @@ -1481,6 +1548,7 @@ + @@ -1499,7 +1567,7 @@ applied. @Target(TYPE) @Retention(RUNTIME) - public @interface MappedSuperclass{} + public @interface MappedSuperclass {} @@ -1553,6 +1621,7 @@ + @Repeatable(NamedEntityGraphs.class) @Target({TYPE}) @Retention(RUNTIME) public @interface NamedEntityGraph { String name() default ""; @@ -1587,24 +1656,34 @@ - + resultClass() default void.class; String resultSetMapping() default ""; //named SqlResultSetMapping + EntityResult[] entities() default {}; + ConstructorResult[] classes() default {}; + ColumnResult[] columns() default {}; } - + ]]> + + + @@ -1617,11 +1696,12 @@ + @Repeatable(NamedQueries.class) @Target({TYPE}) @Retention(RUNTIME) public @interface NamedQuery { String name(); String query(); - LockModeType lockMode() default NONE; + LockModeType lockMode() default LockModeType.NONE; QueryHint[] hints() default {}; } @@ -1643,6 +1723,7 @@ + @Repeatable(NamedStoredProcedureQueries.class) @Target({TYPE}) @Retention(RUNTIME) public @interface NamedStoredProcedureQuery { String name(); @@ -1675,16 +1756,16 @@ - + type() default void.class; NamedAttributeNode[] attributeNodes(); } - + ]]> - + targetEntity() default void.class; CascadeType[] cascade() default {}; - FetchType fetch() default LAZY; + FetchType fetch() default FetchType.LAZY; String mappedBy() default ""; + boolean orphanRemoval() default false; } - + ]]> @@ -1779,19 +1861,19 @@ - + targetEntity() default void.class; CascadeType[] cascade() default {}; - FetchType fetch() default EAGER; + FetchType fetch() default FetchType.EAGER; boolean optional() default true; String mappedBy() default ""; boolean orphanRemoval() default false; } - + ]]> @@ -1824,7 +1906,7 @@ - + @@ -1855,6 +1937,7 @@ boolean insertable() default true; boolean updatable() default true; String columnDefinition() default ""; + String options() default ""; } @@ -1864,6 +1947,7 @@ + @@ -1872,7 +1956,7 @@ - public enum ParameterMode { IN, INOUT, OUT, REF_CURSOR}; + public enum ParameterMode { IN, INOUT, OUT, REF_CURSOR } @@ -2009,18 +2093,26 @@ + @Repeatable(PrimaryKeyJoinColumns.class) @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) public @interface PrimaryKeyJoinColumn { String name() default ""; String referencedColumnName() default ""; String columnDefinition() default ""; + String options() default ""; + ForeignKey foreignKey() default @ForeignKey(PROVIDER_DEFAULT); } + + + + @@ -2050,14 +2142,19 @@ + @Repeatable(SecondaryTables.class) @Target({TYPE}) @Retention(RUNTIME) public @interface SecondaryTable { String name(); String catalog() default ""; String schema() default ""; PrimaryKeyJoinColumn[] pkJoinColumns() default {}; + ForeignKey foreignKey() default @ForeignKey(ConstraintMode.PROVIDER_DEFAULT); UniqueConstraint[] uniqueConstraints() default {}; Index[] indexes() default {}; + CheckConstraint[] check() default {}; + String comment() default ""; + String options() default ""; } @@ -2075,10 +2172,16 @@ minOccurs="0" maxOccurs="unbounded"/> + + + + @@ -2087,14 +2190,16 @@ - @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) + @Repeatable(SequenceGenerators.class) + @Target({TYPE, METHOD, FIELD, PACKAGE}) @Retention(RUNTIME) public @interface SequenceGenerator { - String name(); + String name() default ""; String sequenceName() default ""; String catalog() default ""; String schema() default ""; int initialValue() default 1; int allocationSize() default 50; + String options() default ""; } @@ -2102,12 +2207,13 @@ - + + @@ -2116,6 +2222,7 @@ + @Repeatable(SqlResultSetMappings.class) @Target({TYPE}) @Retention(RUNTIME) public @interface SqlResultSetMapping { String name(); @@ -2142,16 +2249,16 @@ - + type(); } - + ]]> @@ -2184,10 +2294,14 @@ minOccurs="0" maxOccurs="unbounded"/> + + + @@ -2196,9 +2310,10 @@ - @Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME) + @Repeatable(TableGenerators.class) + @Target({TYPE, METHOD, FIELD, PACKAGE}) @Retention(RUNTIME) public @interface TableGenerator { - String name(); + String name() default ""; String table() default ""; String catalog() default ""; String schema() default ""; @@ -2209,6 +2324,7 @@ int allocationSize() default 50; UniqueConstraint[] uniqueConstraints() default {}; Indexes[] indexes() default {}; + String options() default ""; } @@ -2219,8 +2335,10 @@ minOccurs="0" maxOccurs="unbounded"/> + - + @@ -2229,6 +2347,7 @@ + @@ -2253,6 +2372,7 @@ + @Deprecated(since = "3.2") public enum TemporalType { DATE, // java.sql.Date TIME, // java.sql.Time @@ -2292,6 +2412,7 @@ public @interface UniqueConstraint { String name() default ""; String[] columnNames(); + String options() default ""; } @@ -2301,6 +2422,7 @@ maxOccurs="unbounded"/> + ```

[gavinking]

OK, great, will do.

Also, @sebersole, since you're more fluent in the XML schema, it would be great if you could take a look too.

[sebersole]

Not sure I'd say I'm more fluent, just been doing a lot of XSD/JAXB lately ;)

The changes looked fine. A good chunk are just documentation changes and adding a new "options" value for various database objects.

[gavinking]

Great, thanks.

[sebersole]

A few minor things I did notice -

1. I suggest making comment an element, whereas it is currently defined as an attribute.
2. Maybe options as well?
3. To help with any on-going maintenance, I'd consider better use of XSD groups to extract common stuff. E.g. move things that are common across <table/>, <secondary-table/>, <join-table/>, ... into a group.

(1) and (2) because those might be long/complex. And a side benefit being that it helps with (3).

The argument for (3) is just that, e.g., it would have made much of this change simpler. You could have added table-related check, comment and options in a single place - the group. E.g. from Hibernate's XSD -

    <xsd:group name="common-table-group">
        <xsd:annotation>
            <xsd:documentation>
                See `@org.hibernate.annotations.Comment`
                See `@org.hibernate.annotations.Check`
            </xsd:documentation>
        </xsd:annotation>
        <xsd:sequence>
            <xsd:element name="check" type="orm:check-constraint" minOccurs="0" />
            <xsd:element name="options" type="xsd:string" minOccurs="0" />
            <xsd:element name="comment" type="xsd:string" minOccurs="0" />
        </xsd:sequence>
    </xsd:group>

    <xsd:complexType name="table">
        ...
        <xsd:sequence>
            <xsd:group ref="common-table-group" />
            <xsd:element name="unique-constraint" type="orm:unique-constraint" minOccurs="0" maxOccurs="unbounded"/>
            <xsd:element name="index" type="orm:index" minOccurs="0" maxOccurs="unbounded"/>
            ...
        </xsd:sequence>
        ...
    <xsd:complexType/>

With the group, you'd make that change once in one spot.

[gavinking]

I suggest making comment an element, whereas it is currently defined as an attribute.

That sounds good to me. WDYT, @lukasj ?

Maybe options as well?

This one I don't care about. I think the idea is that it should be something short that fits in an attribute.

To help with any on-going maintenance, I'd consider better use of XSD groups to extract common stuff.

That's a very good idea, but it's something we could open a separate issue for.

[sebersole]

Maybe options as well?

This one I don't care about. I think the idea is that it should be something short that fits in an attribute

It's about intention and XSD capabilities. E.g., for a column do you see column-definition and options as mutually exclusive? It would seem like they are. But at the moment, you cannot enforce that in the XSD. And unfortunately you won't be able to because column-definition is already an attribute. In XSD you can only force a choice between elements.

Just suggesting we might want to be proactive about that

[gavinking]

for a column do you see column-definition and options as mutually exclusive?

We did not say that. Right now you can use them together. But I agree that's not very useful and in principle we could make them mutually exclusive.

I don't have an opinion either way.

[lukasj]

I'll move comment to become an element

[lukasj]

I changed comment from an attribute to an element. For options, I kept it as an attribute for now (no strong opinion here, I'm only thinking that this is going to be used for something short). For the last item, I filed #546 as I think that it deserves separate PR

[gavinking]

I'm only thinking that this is going to be used for something short

Yeah, I think that's most likely.