Skip to content

Commit

Permalink
#508: Update sample code in javadoc to use @snippet (#536)
Browse files Browse the repository at this point in the history
Signed-off-by: Lukas Jungmann <[email protected]>
  • Loading branch information
lukasj authored Nov 3, 2023
1 parent 6505741 commit 4f1c5e1
Show file tree
Hide file tree
Showing 64 changed files with 1,255 additions and 1,184 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/maven.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ jobs:

strategy:
matrix:
java_version: [ 17, 21 ]
java_version: [ 21 ]

steps:
- name: Checkout for build
Expand Down
3 changes: 1 addition & 2 deletions api/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,7 @@
<legal.doc.source>${project.basedir}/..</legal.doc.source>
<vendor.name>Eclipse Foundation</vendor.name>

<maven.compiler.release>17</maven.compiler.release>
<project.build.outputTimestamp>2023-10-28T00:00:00Z</project.build.outputTimestamp>
</properties>

Expand Down Expand Up @@ -272,7 +273,6 @@
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<release>17</release>
<compilerArgs>
<arg>-Xlint:all</arg>
</compilerArgs>
Expand Down Expand Up @@ -335,7 +335,6 @@
<addDefaultEntries>false</addDefaultEntries>
</manifest>
</archive>
<release>11</release>
<quiet>true</quiet>
<notimestamp>true</notimestamp>
<docfilessubdirs>true</docfilessubdirs>
Expand Down
89 changes: 45 additions & 44 deletions api/src/main/java/jakarta/persistence/AssociationOverride.java
Original file line number Diff line number Diff line change
Expand Up @@ -66,55 +66,56 @@
*
* <p>Example 1: Overriding the mapping of a relationship defined by a
* mapped superclass
* <pre>
* &#064;MappedSuperclass
* public class Employee {
* ...
* &#064;ManyToOne
* protected Address address;
* ...
* }
* {@snippet :
* @MappedSuperclass
* public class Employee {
* ...
* @ManyToOne
* protected Address address;
* ...
* }
*
* &#064;Entity
* &#064;AssociationOverride(name="address",
* joinColumns=&#064;JoinColumn(name="ADDR_ID"))
* // address field mapping overridden to ADDR_ID foreign key
* public class PartTimeEmployee extends Employee {
* ...
* }
* </pre>
* @Entity
* @AssociationOverride(name = "address",
* joinColumns = @JoinColumn(name = "ADDR_ID"))
* // address field mapping overridden to ADDR_ID foreign key
* public class PartTimeEmployee extends Employee {
* ...
* }
* }
*
* <p>Example 2: Overriding the mapping for {@code phoneNumbers} defined
* in the {@code ContactInfo} class
* <pre>
* &#064;Entity
* public class Employee {
* &#064;Id int id;
* &#064;AssociationOverride(
* name="phoneNumbers",
* joinTable=&#064;JoinTable(
* name="EMPPHONES",
* joinColumns=&#064;JoinColumn(name="EMP"),
* inverseJoinColumns=&#064;JoinColumn(name="PHONE")
* )
* )
* &#064;Embedded ContactInfo contactInfo;
* ...
* }
* {@snippet :
* @Entity
* public class Employee {
* @Id int id;
* @AssociationOverride(
* name = "phoneNumbers",
* joinTable = @JoinTable(name = "EMPPHONES",
* joinColumns = @JoinColumn(name = "EMP"),
* inverseJoinColumns = @JoinColumn(name = "PHONE")))
* @Embedded
* ContactInfo contactInfo;
* ...
* }
*
* &#064;Embeddable
* public class ContactInfo {
* &#064;ManyToOne Address address; // Unidirectional
* &#064;ManyToMany(targetEntity=PhoneNumber.class) List phoneNumbers;
* }
*
* &#064;Entity
* public class PhoneNumber {
* &#064;Id int number;
* &#064;ManyToMany(mappedBy="contactInfo.phoneNumbers")
* Collection&#060;Employee&#062; employees;
* }
* </pre>
* @Embeddable
* public class ContactInfo {
* @ManyToOne
* Address address; // Unidirectional
* @ManyToMany(targetEntity = PhoneNumber.class)
* List phoneNumbers;
* }
*
* @Entity
* public class PhoneNumber {
* @Id
* int number;
* @ManyToMany(mappedBy = "contactInfo.phoneNumbers")
* Collection<Employee> employees;
* }
* }
*
* @see Embedded
* @see Embeddable
Expand Down
55 changes: 29 additions & 26 deletions api/src/main/java/jakarta/persistence/AssociationOverrides.java
Original file line number Diff line number Diff line change
Expand Up @@ -27,35 +27,38 @@
* Used to override mappings of multiple relationship properties or fields.
*
* <p>Example:
* <pre>
* &#064;MappedSuperclass
* public class Employee {
* {@snippet :
* @MappedSuperclass
* public class Employee {
*
* &#064;Id protected Integer id;
* &#064;Version protected Integer version;
* &#064;ManyToOne protected Address address;
* &#064;OneToOne protected Locker locker;
* @Id
* protected Integer id;
* @Version
* protected Integer version;
* @ManyToOne
* protected Address address;
* @OneToOne
* protected Locker locker;
*
* public Integer getId() { ... }
* public void setId(Integer id) { ... }
* public Address getAddress() { ... }
* public void setAddress(Address address) { ... }
* public Locker getLocker() { ... }
* public void setLocker(Locker locker) { ... }
* ...
* }
* public Integer getId() { ... }
* public void setId(Integer id) { ... }
* public Address getAddress() { ... }
* public void setAddress(Address address) { ... }
* public Locker getLocker() { ... }
* public void setLocker(Locker locker) { ... }
* ...
* }
*
* &#064;Entity
* &#064;AssociationOverrides({
* &#064;AssociationOverride(
* name="address",
* joinColumns=&#064;JoinColumn("ADDR_ID")),
* &#064;AttributeOverride(
* name="locker",
* joinColumns=&#064;JoinColumn("LCKR_ID"))
* })
* public PartTimeEmployee { ... }
* </pre>
* @Entity
* @AssociationOverrides({
* @AssociationOverride(
* name = "address",
* joinColumns = @JoinColumn("ADDR_ID")),
* @AttributeOverride(
* name = "locker",
* joinColumns = @JoinColumn("LCKR_ID"))})
* public PartTimeEmployee { ... }
* }
*
*@see AssociationOverride
*
Expand Down
144 changes: 80 additions & 64 deletions api/src/main/java/jakarta/persistence/AttributeOverride.java
Original file line number Diff line number Diff line change
Expand Up @@ -51,78 +51,94 @@
* mapped the same as in the original mapping.
*
* <p>Example 1:
* <pre>
* &#064;MappedSuperclass
* public class Employee {
* &#064;Id protected Integer id;
* &#064;Version protected Integer version;
* protected String address;
* public Integer getId() { ... }
* public void setId(Integer id) { ... }
* public String getAddress() { ... }
* public void setAddress(String address) { ... }
* }
* {@snippet :
* @MappedSuperclass
* public class Employee {
* @Id
* protected Integer id;
* @Version
* protected Integer version;
* protected String address;
* public Integer getId() { ... }
* public void setId(Integer id) { ... }
* public String getAddress() { ... }
* public void setAddress(String address) { ... }
* }
*
* &#064;Entity
* &#064;AttributeOverride(name="address", column=&#064;Column(name="ADDR"))
* public class PartTimeEmployee extends Employee {
* // address field mapping overridden to ADDR
* protected Float wage();
* public Float getHourlyWage() { ... }
* public void setHourlyWage(Float wage) { ... }
* }
* </pre>
* @Entity
* @AttributeOverride(name = "address", column = @Column(name = "ADDR"))
* public class PartTimeEmployee extends Employee {
* // address field mapping overridden to ADDR
* protected Float wage();
* public Float getHourlyWage() { ... }
* public void setHourlyWage(Float wage) { ... }
* }
* }
*
* <p>Example 2:
* <pre>
* &#064;Embeddable public class Address {
* protected String street;
* protected String city;
* protected String state;
* &#064;Embedded protected Zipcode zipcode;
* }
* {@snippet :
* @Embeddable
* public class Address {
* protected String street;
* protected String city;
* protected String state;
* @Embedded
* protected Zipcode zipcode;
* }
*
* &#064;Embeddable public class Zipcode {
* protected String zip;
* protected String plusFour;
* }
* @Embeddable
* public class Zipcode {
* protected String zip;
* protected String plusFour;
* }
*
* &#064;Entity public class Customer {
* &#064;Id protected Integer id;
* protected String name;
* &#064;AttributeOverrides({
* &#064;AttributeOverride(name="state",
* column=&#064;Column(name="ADDR_STATE")),
* &#064;AttributeOverride(name="zipcode.zip",
* column=&#064;Column(name="ADDR_ZIP"))
* })
* &#064;Embedded protected Address address;
* ...
* }
* </pre>
* @Entity
* public class Customer {
* @Id
* protected Integer id;
* protected String name;
* @AttributeOverride(name = "state",
* column = @Column(name = "ADDR_STATE"))
* @AttributeOverride(name = "zipcode.zip",
* column = @Column(name = "ADDR_ZIP"))
* @Embedded
* protected Address address;
* ...
* }
* }
*
* <p>Example 3:
* <pre>
* &#064;Entity public class PropertyRecord {
* &#064;EmbeddedId PropertyOwner owner;
* &#064;AttributeOverrides({
* &#064;AttributeOverride(name="key.street",
* column=&#064;Column(name="STREET_NAME")),
* &#064;AttributeOverride(name="value.size",
* column=&#064;Column(name="SQUARE_FEET")),
* &#064;AttributeOverride(name="value.tax",
* column=&#064;Column(name="ASSESSMENT"))
* })
* &#064;ElementCollection
* Map&#060;Address, PropertyInfo&#062; parcels;
* }
* {@snippet :
* @Entity
* public class PropertyRecord {
* @EmbeddedId
* protected PropertyOwner owner;
* @AttributeOverride(name = "key.street",
* column = @Column(name = "STREET_NAME"))
* @AttributeOverride(name = "value.size",
* column = @Column(name = "SQUARE_FEET"))
* @AttributeOverride(name = "value.tax",
* column = @Column(name = "ASSESSMENT"))
* @ElementCollection
* protected Map<Address, PropertyInfo> parcels;
* }
*
* &#064;Embeddable public class PropertyInfo {
* Integer parcelNumber;
* Integer size;
* BigDecimal tax;
* }
* </pre>
* @Embeddable
* public class Address {
* protected String street;
* protected String city;
* protected String state;
* @Embedded
* protected Zipcode zipcode;
* }
*
* @Embeddable
* public class PropertyInfo {
* Integer parcelNumber;
* Integer size;
* BigDecimal tax;
* }
* }
*
* @see Embedded
* @see Embeddable
Expand Down
23 changes: 10 additions & 13 deletions api/src/main/java/jakarta/persistence/AttributeOverrides.java
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
/*
* Copyright (c) 2022, 2023 Contributors to the Eclipse Foundation
* Copyright (c) 2008, 2020 Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2008, 2023 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0 which is available at
Expand Down Expand Up @@ -28,20 +28,17 @@
* Used to override mappings of multiple properties or fields.
*
* <p>Example:
* <pre>
* &#064;Embedded
* &#064;AttributeOverrides({
* &#064;AttributeOverride(name="startDate",
* column=&#064;Column(name="EMP_START")),
* &#064;AttributeOverride(name="endDate",
* column=&#064;Column(name="EMP_END"))
* })
* public EmploymentPeriod getEmploymentPeriod() { ... }
* </pre>
*
* {@snippet :
* @Embedded
* @AttributeOverrides({
* @AttributeOverride(name = "startDate",
* column = @Column(name = "EMP_START")),
* @AttributeOverride(name="endDate",
* column = @Column(name = "EMP_END"))})
* public EmploymentPeriod getEmploymentPeriod() { ... }
* }
*
* @see AttributeOverride
*
* @since 1.0
*/
@Target({TYPE, METHOD, FIELD})
Expand Down
Loading

0 comments on commit 4f1c5e1

Please sign in to comment.