Skip to content

feat: ESPI 4.0 Schema Compliance - Phase 19: Statement Complete Implementation #102

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dfcoffin merged 3 commits into from
Feb 3, 2026
Merged

feat: ESPI 4.0 Schema Compliance - Phase 19: Statement Complete Implementation #102

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dd72192
feat: ESPI 4.0 Schema Compliance - Phase 19: Statement Complete Imple…
dfcoffin Feb 2, 2026
9f0edb3
test: Add comprehensive test suite for Phase 19 Statement implementation
dfcoffin Feb 2, 2026
dcd6e1e
fix: Truncate timestamps to microseconds for cross-platform compatibi…
dfcoffin Feb 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 33 additions & 4 deletions ...main/java/org/greenbuttonalliance/espi/common/domain/customer/entity/StatementEntity.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,18 +56,44 @@ public class StatementEntity extends IdentifiedObject {

/**
* [extension] Contains document reference metadata needed to access a document representation of a billing statement.
* StatementRef extends Object (not IdentifiedObject), so stored as @ElementCollection.
*/
@OneToMany(mappedBy = "statement", cascade = CascadeType.ALL, fetch = FetchType.LAZY)
@ElementCollection(fetch = FetchType.LAZY)
@CollectionTable(name = "statement_refs", joinColumns = @JoinColumn(name = "statement_id"))
private List<StatementRefEntity> statementRefs;

/**
* Customer that owns this statement.
* Customer associated with this statement.
* Many statements can belong to one customer.
*/
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "customer_id")
private CustomerEntity customer;

/**
* Customer account associated with this statement.
* Many statements can belong to one customer account.
*/
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "customer_account_id")
private CustomerAccountEntity customerAccount;

/**
* Customer agreement associated with this statement.
* Many statements can belong to one customer agreement.
*/
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "customer_agreement_id")
private CustomerAgreementEntity customerAgreement;

/**
* Usage summary associated with this statement.
* Many statements can belong to one usage summary.
*/
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "usage_summary_id")
private org.greenbuttonalliance.espi.common.domain.usage.UsageSummaryEntity usageSummary;

@Override
public final boolean equals(Object o) {
if (this == o) return true;
Expand All @@ -88,10 +114,13 @@ public final int hashCode() {
public String toString() {
return getClass().getSimpleName() + "(" +
"id = " + getId() + ", " +
"issueDateTime = " + getIssueDateTime() + ", " +
"description = " + getDescription() + ", " +
"created = " + getCreated() + ", " +
"updated = " + getUpdated() + ", " +
"published = " + getPublished() + ")";
"published = " + getPublished() + ", " +
"upLink = " + getUpLink() + ", " +
"selfLink = " + getSelfLink() + ", " +
"issueDateTime = " + getIssueDateTime() + ", " +
"relatedLinks = " + getRelatedLinks() + ")";
}
}
75 changes: 14 additions & 61 deletions ...n/java/org/greenbuttonalliance/espi/common/domain/customer/entity/StatementRefEntity.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,40 +19,28 @@

package org.greenbuttonalliance.espi.common.domain.customer.entity;

import jakarta.persistence.*;
import lombok.Getter;
import jakarta.persistence.Column;
import jakarta.persistence.Embeddable;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.Setter;
import org.hibernate.annotations.JdbcTypeCode;
import org.hibernate.proxy.HibernateProxy;
import org.hibernate.type.SqlTypes;
import lombok.ToString;

import java.util.Objects;
import java.util.UUID;
import java.io.Serializable;

/**
* Pure JPA/Hibernate entity for StatementRef without JAXB concerns.
* Embeddable class for StatementRef without JAXB concerns.
*
* [extension] A sequence of references to a document associated with a Statement.
*
* Note: StatementRef does NOT extend IdentifiedObject per ESPI 4.0 specification.
* It is not a top-level resource with selfLink/upLink/relatedLinks.
* Note: StatementRef extends Object (not IdentifiedObject) per customer.xsd lines 285-307.
* It is not a top-level resource and has no selfLink/upLink/relatedLinks.
* Stored as @ElementCollection in StatementEntity.
*/
@Entity
@Table(name = "statement_refs")
@Getter
@Setter
@Embeddable
@Data
@NoArgsConstructor
public class StatementRefEntity {

/**
* Primary key identifier.
*/
@Id
@GeneratedValue(strategy = GenerationType.UUID)
@JdbcTypeCode(SqlTypes.CHAR)
@Column(length = 36, columnDefinition = "char(36)", updatable = false, nullable = false)
private UUID id;
@ToString
public class StatementRefEntity implements Serializable {

/**
* [extension] Name of document or file including filename extension if present.
Expand All @@ -67,44 +55,9 @@ public class StatementRefEntity {
private String mediaType;

/**
* [extension] URL used to access a representation of a statement, for example a bill image.
* [extension] URL used to access a representation of a statement, for example a bill image.
* Use CDATA or URL encoding to escape characters not allowed in XML.
*/
@Column(name = "statement_url", length = 2048)
private String statementURL;

/**
* Statement this reference belongs to
*/
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "statement_id")
private StatementEntity statement;

@Override
public final boolean equals(Object o) {
if (this == o) return true;
if (o == null) return false;
Class<?> oEffectiveClass = o instanceof HibernateProxy hibernateProxy ?
hibernateProxy.getHibernateLazyInitializer().getPersistentClass() : o.getClass();
Class<?> thisEffectiveClass = this instanceof HibernateProxy hibernateProxy ?
hibernateProxy.getHibernateLazyInitializer().getPersistentClass() : this.getClass();
if (thisEffectiveClass != oEffectiveClass) return false;
StatementRefEntity that = (StatementRefEntity) o;
return getId() != null && Objects.equals(getId(), that.getId());
}

@Override
public final int hashCode() {
return this instanceof HibernateProxy hibernateProxy ?
hibernateProxy.getHibernateLazyInitializer().getPersistentClass().hashCode() : getClass().hashCode();
}

@Override
public String toString() {
return getClass().getSimpleName() + "(" +
"id = " + getId() + ", " +
"fileName = " + getFileName() + ", " +
"mediaType = " + getMediaType() + ", " +
"statementURL = " + getStatementURL() + ")";
}
}
101 changes: 21 additions & 80 deletions ...i-common/src/main/java/org/greenbuttonalliance/espi/common/dto/customer/StatementDto.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,109 +19,50 @@

package org.greenbuttonalliance.espi.common.dto.customer;

import org.greenbuttonalliance.espi.common.dto.atom.LinkDto;

import jakarta.xml.bind.annotation.*;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;

import java.time.OffsetDateTime;
import java.util.List;

/**
* Statement DTO class for JAXB XML marshalling/unmarshalling.
* Statement DTO for JAXB XML marshalling/unmarshalling.
*
* [extension] Billing statement for provided services.
*
* Corresponds to customer.xsd Statement definition (lines 373-393).
* Statement extends IdentifiedObject, but DTO excludes IdentifiedObject fields
* (id, description, published, updated, links) as they're handled by Atom Entry wrapper.
*
* Represents a billing statement or document for a customer agreement.
* Supports Atom protocol XML wrapping.
* ESPI 4.0 XSD Sequence (customer.xsd lines 379-392):
* 1. issueDateTime (TimeType) - optional
* 2. statementRef (StatementRef collection) - optional, unbounded
*/
@XmlRootElement(name = "Statement", namespace = "http://naesb.org/espi/customer")
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "Statement", namespace = "http://naesb.org/espi/customer", propOrder = {
"published", "updated", "selfLink", "upLink", "relatedLinks",
"description", "createdDateTime", "lastModifiedDateTime", "revisionNumber",
"subject", "docStatus", "type", "customerAgreement", "statementRefs"
"issueDateTime",
"statementRef"
})
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class StatementDto {

@XmlTransient
private Long id;

@XmlAttribute(name = "mRID")
private String uuid;

@XmlElement(name = "published")
private OffsetDateTime published;

@XmlElement(name = "updated")
private OffsetDateTime updated;

@XmlElement(name = "link", namespace = "http://www.w3.org/2005/Atom")
@XmlElementWrapper(name = "links", namespace = "http://www.w3.org/2005/Atom")
private List<LinkDto> relatedLinks;

@XmlElement(name = "link", namespace = "http://www.w3.org/2005/Atom")
private LinkDto selfLink;

@XmlElement(name = "link", namespace = "http://www.w3.org/2005/Atom")
private LinkDto upLink;

@XmlElement(name = "description")
private String description;

@XmlElement(name = "createdDateTime")
private OffsetDateTime createdDateTime;

@XmlElement(name = "lastModifiedDateTime")
private OffsetDateTime lastModifiedDateTime;

@XmlElement(name = "revisionNumber")
private String revisionNumber;

@XmlElement(name = "subject")
private String subject;

@XmlElement(name = "docStatus")
private String docStatus;

@XmlElement(name = "type")
private String type;

@XmlElement(name = "CustomerAgreement")
private CustomerAgreementDto customerAgreement;

@XmlElement(name = "StatementRef")
@XmlElementWrapper(name = "StatementRefs")
private List<StatementRefDto> statementRefs;

/**
* Minimal constructor for basic statement data.
*/
public StatementDto(String uuid, String subject) {
this(null, uuid, null, null, null, null, null, null,
null, null, null, subject, null, null, null, null);
}

/**
* Gets the self href for this statement.
*
* @return self href string
* [extension] Date and time at which a billing statement was issued.
* Stored as Unix epoch timestamp (seconds since 1970-01-01T00:00:00Z).
*/
public String getSelfHref() {
return selfLink != null ? selfLink.getHref() : null;
}
@XmlElement(name = "issueDateTime", namespace = "http://naesb.org/espi/customer")
private Long issueDateTime;

/**
* Gets the up href for this statement.
*
* @return up href string
* [extension] Contains document reference metadata needed to access a document
* representation of a billing statement.
*/
public String getUpHref() {
return upLink != null ? upLink.getHref() : null;
}
}
@XmlElement(name = "statementRef", namespace = "http://naesb.org/espi/customer")
private List<StatementRefDto> statementRef;
}
56 changes: 27 additions & 29 deletions ...ommon/src/main/java/org/greenbuttonalliance/espi/common/dto/customer/StatementRefDto.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,51 +25,49 @@
import lombok.NoArgsConstructor;
import lombok.Setter;

import java.time.OffsetDateTime;

/**
* StatementRef DTO class for JAXB XML marshalling/unmarshalling.
* StatementRef DTO for JAXB XML marshalling/unmarshalling.
*
* Represents a reference to a statement document.
* [extension] A sequence of references to a document associated with a Statement.
*
* Note: StatementRef does NOT extend IdentifiedObject per ESPI 4.0 specification.
* It is not a top-level resource with selfLink/upLink/relatedLinks.
* Corresponds to customer.xsd StatementRef definition (lines 285-307).
* StatementRef extends Object (not IdentifiedObject), so it has no id/links/metadata.
*
* WARNING: DTO fields do not currently match entity fields.
* Entity has: fileName, mediaType, statementURL
* DTO has: referenceId, referenceType, referenceDate, referenceUrl
* This mismatch needs to be resolved.
* ESPI 4.0 XSD Sequence (customer.xsd lines 291-306):
* 1. fileName (String256) - optional
* 2. mediaType (String256) - optional
* 3. statementURL (String2048) - optional
*/
@XmlRootElement(name = "StatementRef", namespace = "http://naesb.org/espi/customer")
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "StatementRef", namespace = "http://naesb.org/espi/customer", propOrder = {
"referenceId", "referenceType", "referenceDate", "referenceUrl", "statement"
"fileName",
"mediaType",
"statementURL"
})
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class StatementRefDto {

@XmlElement(name = "referenceId")
private String referenceId;

@XmlElement(name = "referenceType")
private String referenceType;

@XmlElement(name = "referenceDate")
private OffsetDateTime referenceDate;

@XmlElement(name = "referenceUrl")
private String referenceUrl;
/**
* [extension] Name of document or file including filename extension if present.
*/
@XmlElement(name = "fileName", namespace = "http://naesb.org/espi/customer")
private String fileName;

@XmlElement(name = "Statement")
private StatementDto statement;
/**
* [extension] Document media type as published by IANA.
* See https://www.iana.org/assignments/media-types for more information.
*/
@XmlElement(name = "mediaType", namespace = "http://naesb.org/espi/customer")
private String mediaType;

/**
* Minimal constructor for basic reference data.
* [extension] URL used to access a representation of a statement, for example a bill image.
* Use CDATA or URL encoding to escape characters not allowed in XML.
*/
public StatementRefDto(String referenceId, String referenceUrl) {
this(referenceId, null, null, referenceUrl, null);
}
}
@XmlElement(name = "statementURL", namespace = "http://naesb.org/espi/customer")
private String statementURL;
}
Loading
Loading