Skip to content
Open
5 changes: 2 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,15 +129,15 @@ Note: ServiceSupplier has an entity, DTO, and mapper but no repository or servic

### REST API Structure
REST controllers are in `openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/`:
- **web/api/** - ESPI RESTful API endpoints. GET-only (feed + entry) for ApplicationInformation, Authorization, Customer, CustomerAccount, UsagePoint, MeterReading, ReadingType, IntervalBlock, UsageSummary, ElectricPowerQualitySummary. `web/api/scope/` holds `ScopeResolver`, `ResourceScope`, `EspiQueryOptions` (not yet wired into controllers).
- **web/api/** - ESPI RESTful API endpoints. GET-only (feed + entry) for ApplicationInformation, Authorization, Customer, CustomerAccount, UsagePoint, MeterReading, ReadingType, IntervalBlock, UsageSummary, ElectricPowerQualitySummary, plus `Batch/Subscription/{id}` (#279: `BatchSubscriptionController` + `SubscriptionFeedAssembler`, one feed of the subscription's usage data; access via `ScopeResolver.canReadSubscription`). `web/api/scope/` holds `ScopeResolver`, `ResourceScope`, `EspiQueryOptions` (`ResourceScope`/`EspiQueryOptions` not yet wired into the per-resource controllers).
- **web/custodian/** - Data custodian admin portal (home, BatchList notification send, settings)
- **web/customer/** - Retail customer portal; most classes here are original legacy code with `@Controller` commented out
- **web/authorize/** - Customer authorization (per-FB consent) screen delegated from the AS
- **internal/backchannel/** - AS→DC subscription-provisioning back-channel

Current state (see GitHub epic #119 "CANONICAL BUILD PLAN" for the roadmap):
- All write endpoints (POST/PUT/DELETE) were deliberately removed in #166 and are deferred.
- Not yet implemented: `Batch/Subscription`, `Batch/Bulk`, `Batch/RetailCustomer`, `Subscription/{id}`, RetailCustomer-scoped URIs, LocalTimeParameters, ReadServiceStatus, and the CustomerAgreement/ServiceSupplier/ServiceLocation/Meter/EndDevice/Statement/ProgramIdMappings endpoints.
- Not yet implemented: `Batch/Bulk`, `Batch/RetailCustomer`, `Subscription/{id}`, RetailCustomer-scoped URIs, LocalTimeParameters, ReadServiceStatus, and the CustomerAgreement/ServiceSupplier/ServiceLocation/Meter/EndDevice/Statement/ProgramIdMappings endpoints.
- Known defect: Subscription-scoped GETs currently ignore `subscriptionId` and return all records.
- The ten per-resource controllers duplicate find/map/marshal logic; the E1 resource engine (#187, branch `feature/187-e1-resource-engine-usagepoint-triad`, not yet merged) replaces them with one generic controller driven by `EspiResource` + `ResourceFbPolicy` (added in `openespi-common/.../common/scope/` on that branch, alongside the existing `FunctionBlock`).

Expand Down Expand Up @@ -358,7 +358,6 @@ Still in progress (logic migration from the original OpenESPI code):
The source of truth for status and roadmap is GitHub epic #119 ("CANONICAL BUILD PLAN") and its sub-issues. The root `PHASE_*.md`, `MULTI_PHASE_SCHEMA_COMPLIANCE_PLAN.md`, `ISSUE_101_*.md`, `openespi-common/Phase_A-Flyway_Migration_Inventory.md`, `openespi-common/PROFILE_MIGRATION_SUMMARY.md`, `openespi-datacustodian/controll-update-status.md`, and `openespi-authserver/MIGRATION_ROADMAP.md` are historical and stale.

Known rule violations / defects to be aware of:
- `domain/common/DateTimeInterval` carries `@XmlType` despite being an `@Embeddable` (violates the JAXB rule above; collides with `DateTimeIntervalDto`)
- `MeterMapper` ignores meter multipliers (silently dropped on export/import)
- Five orphaned `*_related_links` tables are still created in the vendor V2 scripts

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,6 @@

import jakarta.persistence.Column;
import jakarta.persistence.Embeddable;
import jakarta.xml.bind.annotation.XmlAccessType;
import jakarta.xml.bind.annotation.XmlAccessorType;
import jakarta.xml.bind.annotation.XmlElement;
import jakarta.xml.bind.annotation.XmlType;

/**
* Date and time interval with duration.
Expand All @@ -41,14 +37,14 @@
*
* <p>Per ESPI 4.0 espi.xsd lines 1337-1357.
*
* <p>JPA only: the XML form is {@code DateTimeIntervalDto} (usage) or {@code CustomerDateTimeIntervalDto}
* (customer). The JAXB annotations this class used to carry declared the same XML type as
* {@code DateTimeIntervalDto}, which broke the Data Custodian's JAXB context once the DTO was put in the espi
* namespace (#279; see CLAUDE.md, JAXB Annotation Guidelines).
*
* @see <a href="http://naesb.org/espi">ESPI Specification</a>
*/
@Embeddable
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "DateTimeInterval", namespace = "http://naesb.org/espi", propOrder = {
"duration",
"start"
})
@Getter
@Setter
@NoArgsConstructor
Expand All @@ -62,7 +58,6 @@ public class DateTimeInterval {
* <p>Required field. Type: UInt32 (unsigned 32-bit integer, max 4,294,967,295).
* XSD: espi.xsd line 1344
*/
@XmlElement(name = "duration", namespace = "http://naesb.org/espi", required = true)
@Column(name = "duration", nullable = false)
private Long duration;

Expand All @@ -72,7 +67,6 @@ public class DateTimeInterval {
* <p>Required field. Type: TimeType (seconds since Unix epoch, Jan 1, 1970 UTC).
* XSD: espi.xsd line 1349
*/
@XmlElement(name = "start", namespace = "http://naesb.org/espi", required = true)
@Column(name = "start", nullable = false)
private Long start;

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,10 @@

package org.greenbuttonalliance.espi.common.domain.usage.enums;

import org.greenbuttonalliance.espi.common.domain.common.ServiceCategory;

import java.util.Optional;

import jakarta.xml.bind.annotation.XmlEnum;
import jakarta.xml.bind.annotation.XmlEnumValue;
import jakarta.xml.bind.annotation.XmlType;
Expand Down Expand Up @@ -118,4 +122,23 @@ public static ServiceKind fromValue(int value) {
}
throw new IllegalArgumentException("Invalid ServiceKind value: " + value);
}

/**
* The ServiceKind of a UsagePoint's {@link ServiceCategory}, matched by espi.xsd code (both enums carry the
* ServiceKind codes 0-9; their constant names differ, e.g. TV_LICENSE / TV_LICENCE). The one mapping used by
* the consent screen and the Batch/Subscription feed.
*
* @return the kind, or empty for null or a code with no ServiceKind
*/
public static Optional<ServiceKind> of(ServiceCategory category) {
if (category == null || category.getValue() == null) {
return Optional.empty();
}
for (ServiceKind kind : values()) {
if (kind.value == category.getValue()) {
return Optional.of(kind);
}
}
return Optional.empty();
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,8 @@ public static class Content {
@XmlElement(name = "ReadingType", type = ReadingTypeDto.class, namespace = "http://naesb.org/espi"),
@XmlElement(name = "ElectricPowerQualitySummary", type = ElectricPowerQualitySummaryDto.class, namespace = "http://naesb.org/espi"),
@XmlElement(name = "UsageSummary", type = UsageSummaryDto.class, namespace = "http://naesb.org/espi"),
@XmlElement(name = "TimeConfiguration", type = TimeConfigurationDto.class, namespace = "http://naesb.org/espi"),
// espi.xsd: <xs:element name="LocalTimeParameters" type="TimeConfiguration"/> (#279)
@XmlElement(name = "LocalTimeParameters", type = TimeConfigurationDto.class, namespace = "http://naesb.org/espi"),
@XmlElement(name = "ApplicationInformation", type = ApplicationInformationDto.class, namespace = "http://naesb.org/espi"),
@XmlElement(name = "Authorization", type = AuthorizationDto.class, namespace = "http://naesb.org/espi"),
@XmlElement(name = "Subscription", type = SubscriptionDto.class, namespace = "http://naesb.org/espi"),
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -34,22 +34,28 @@
*
* Represents a time interval with start and duration.
* Used in various Green Button resources for time-based data.
* <p>
* espi.xsd's {@code DateTimeInterval}: {@code espi:duration} then {@code espi:start}, both in the espi namespace
* (#279). This package has no {@code @XmlSchema}, so without the explicit namespaces they were written
* unqualified, and in the wrong order, failing XSD validation. The customer domain uses
* {@code CustomerDateTimeIntervalDto} (cust namespace). The fields stay declared {@code start, duration}, so
* the all-args constructor keeps its {@code (start, duration)} order.
*/
@XmlRootElement(name = "DateTimeInterval")
@XmlRootElement(name = "DateTimeInterval", namespace = "http://naesb.org/espi")
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "DateTimeInterval", propOrder = {
"start", "duration"
@XmlType(name = "DateTimeInterval", namespace = "http://naesb.org/espi", propOrder = {
"duration", "start"
})
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class DateTimeIntervalDto {

@XmlElement(name = "start")
@XmlElement(name = "start", namespace = "http://naesb.org/espi")
private Long start;

@XmlElement(name = "duration")
@XmlElement(name = "duration", namespace = "http://naesb.org/espi")
private Long duration;

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,6 @@
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
import org.greenbuttonalliance.espi.common.dto.common.DateTimeIntervalDto;

import java.io.Serializable;
import java.time.OffsetDateTime;
Expand Down Expand Up @@ -140,7 +139,7 @@ public class CustomerAgreementDto {
* Date and time interval this agreement is valid (from going into effect to termination).
*/
@XmlElement(name = "validityInterval", namespace = "http://naesb.org/espi/customer")
private DateTimeIntervalDto validityInterval;
private CustomerDateTimeIntervalDto validityInterval;

// ==================== CustomerAgreement fields (customer.xsd lines 159-209) ====================

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
/*
*
* Copyright (c) 2025-2026 Green Button Alliance, Inc.
*
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*/

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

import jakarta.xml.bind.annotation.XmlAccessType;
import jakarta.xml.bind.annotation.XmlAccessorType;
import jakarta.xml.bind.annotation.XmlElement;
import jakarta.xml.bind.annotation.XmlType;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;

import java.io.Serializable;

/**
* customer.xsd's own {@code DateTimeInterval} (cust namespace): {@code duration} then {@code start}, both
* optional. The usage-domain {@code DateTimeIntervalDto} is in the espi namespace, so using it here would put
* espi elements inside customer data and declare a second ESPI namespace in customer feeds (#279).
* <p>
* The all-args constructor takes {@code (start, duration)}, like {@code DateTimeIntervalDto}.
*/
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "DateTimeInterval", namespace = "http://naesb.org/espi/customer", propOrder = {
"duration", "start"
})
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class CustomerDateTimeIntervalDto implements Serializable {

@XmlElement(name = "start", namespace = "http://naesb.org/espi/customer")
private Long start;

@XmlElement(name = "duration", namespace = "http://naesb.org/espi/customer")
private Long duration;
}
Original file line number Diff line number Diff line change
Expand Up @@ -36,10 +36,14 @@
* Complies with NAESB ESPI 4.0 XSD specification.
*
* Field order strictly matches espi.xsd TimeConfiguration element sequence.
* <p>
* The element is {@code espi:LocalTimeParameters}: espi.xsd declares
* {@code <xs:element name="LocalTimeParameters" type="TimeConfiguration"/>} and has no global
* {@code TimeConfiguration} element, so {@code <espi:TimeConfiguration>} fails XSD validation (#279).
*
* @see <a href="https://www.naesb.org/ESPI_Standards.asp">NAESB ESPI 4.0</a>
*/
@XmlRootElement(name = "TimeConfiguration", namespace = "http://naesb.org/espi")
@XmlRootElement(name = "LocalTimeParameters", namespace = "http://naesb.org/espi")
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "TimeConfiguration", namespace = "http://naesb.org/espi", propOrder = {
"dstEndRule",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -94,11 +94,13 @@ default List<TariffRiderRefEntity> tariffRiderRefsDtoToEntityList(TariffRiderRef
* Wraps the list in the TariffRiderRefsDto container.
*
* @param entities the list of tariff rider ref entities
* @return the wrapper DTO containing tariff rider refs, or null if input is null
* @return the wrapper DTO containing tariff rider refs, or null if there are none: espi.xsd's
* {@code TariffRiderRefs} needs at least one {@code tariffRiderRef}, so an empty wrapper is
* invalid, while the element itself is optional (#279)
*/
@Named("entityListToTariffRiderRefsDto")
default TariffRiderRefsDto entityListToTariffRiderRefsDto(List<TariffRiderRefEntity> entities) {
if (entities == null) {
if (entities == null || entities.isEmpty()) {
return null;
}
return new TariffRiderRefsDto(toDtoList(entities));
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -255,35 +255,74 @@ public <E extends IdentifiedObject> void exportFeed(String feedHref, String titl
public <E extends IdentifiedObject> AtomFeedDto buildFeed(String feedHref, String title, List<E> entities,
Function<? super E, ?> toContent) {
Objects.requireNonNull(feedHref, "feedHref");
OffsetDateTime now = OffsetDateTime.now(ZoneOffset.UTC).truncatedTo(ChronoUnit.SECONDS);

List<AtomEntryDto> entries = new ArrayList<>(entities.size());
List<FeedEntry> entries = new ArrayList<>(entities.size());
String resource = null;
for (E entity : entities) {
Object content = toContent.apply(entity);
String entryResource = resourceName(content);
resource = resource == null ? entryResource : resource;
resource = resource == null ? resourceName(content) : resource;
entries.add(new FeedEntry(entity, content,
href(entity.getSelfLink(), feedHref + "/" + entity.getId()),
href(entity.getUpLink(), feedHref), List.of()));
}
// An empty feed has no entry to name its resource, so the href's last segment is used (#197).
return buildFeedOf(feedHref, resource != null ? resource : lastPathSegment(feedHref), title, entries);
}

/**
* One entry of a feed that may mix resource types (e.g. {@code Batch/Subscription}, #279): the
* resource, the DTO carried in its {@code <atom:content>}, its {@code self} and {@code up} hrefs, and
* any {@code related} links (with their {@code espi-feed/...} or {@code espi-entry/...} types).
*/
public record FeedEntry(IdentifiedObject entity, Object content, String selfHref, String upHref,
List<LinkDto> related) {

public FeedEntry {
Objects.requireNonNull(entity, "entity");
Objects.requireNonNull(content, "content");
Objects.requireNonNull(selfHref, "selfHref");
Objects.requireNonNull(upHref, "upHref");
related = related == null ? List.of() : List.copyOf(related);
}
}

/**
* Builds an Atom feed from prepared entries, which may be of different resource types, in the order
* given. Entries are written as described for {@link #buildFeed(String, String, List, Function)}, with
* the given hrefs, and each entry's {@code related} links after {@code self} and {@code up}.
*
* @param feedHref absolute URL of the feed (its self link, and the source of its UUID v5 id)
* @param feedResource the resource named in the feed's self link type ({@code espi-feed/<feedResource>}),
* given explicitly so an empty feed is typed correctly whatever its href ends in
* @param title feed title
* @param feedEntries the entries, in feed order; may be empty
*/
public AtomFeedDto buildFeedOf(String feedHref, String feedResource, String title, List<FeedEntry> feedEntries) {
Objects.requireNonNull(feedHref, "feedHref");
Objects.requireNonNull(feedResource, "feedResource");
OffsetDateTime now = OffsetDateTime.now(ZoneOffset.UTC).truncatedTo(ChronoUnit.SECONDS);

String selfHref = href(entity.getSelfLink(), feedHref + "/" + entity.getId());
String upHref = href(entity.getUpLink(), feedHref);
List<LinkDto> links = List.of(
new LinkDto("self", selfHref, "espi-entry/" + entryResource),
new LinkDto("up", upHref, "espi-feed/" + entryResource));
List<AtomEntryDto> entries = new ArrayList<>(feedEntries.size());
for (FeedEntry feedEntry : feedEntries) {
IdentifiedObject entity = feedEntry.entity();
String entryResource = resourceName(feedEntry.content());
List<LinkDto> links = new ArrayList<>(2 + feedEntry.related().size());
links.add(new LinkDto("self", feedEntry.selfHref(), "espi-entry/" + entryResource));
links.add(new LinkDto("up", feedEntry.upHref(), "espi-feed/" + entryResource));
links.addAll(feedEntry.related());
String entryTitle = entity.getDescription() != null && !entity.getDescription().isBlank()
? entity.getDescription() : entryResource;
entries.add(newEntry("urn:uuid:" + entity.getId(), entryTitle,
utc(entity.getPublished(), entity.getCreated(), now),
utc(entity.getUpdated(), entity.getCreated(), now),
links, content));
List.copyOf(links), feedEntry.content()));
}

AtomFeedDto feed = new AtomFeedDto();
feed.setId("urn:uuid:" + ID_GENERATOR.generateEspiId(feedHref));
feed.setTitle(title);
feed.setUpdated(now);
// atom.xsd requires a type on every link: an empty feed takes the resource from its href (#197).
feed.setLinks(List.of(new LinkDto("self", feedHref,
"espi-feed/" + (resource != null ? resource : lastPathSegment(feedHref)))));
// atom.xsd requires a type on every link.
feed.setLinks(List.of(new LinkDto("self", feedHref, "espi-feed/" + feedResource)));
feed.setEntries(entries);
return feed;
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@

import org.greenbuttonalliance.espi.common.dto.atom.AtomFeedDto;
import org.greenbuttonalliance.espi.common.dto.atom.CustomerAtomEntryDto;
import org.greenbuttonalliance.espi.common.dto.common.DateTimeIntervalDto;
import org.greenbuttonalliance.espi.common.dto.customer.CustomerDateTimeIntervalDto;
import org.greenbuttonalliance.espi.common.service.impl.DtoExportServiceImpl;
import org.greenbuttonalliance.espi.common.dto.customer.ElectronicAddressDto;
import org.junit.jupiter.api.BeforeEach;
Expand Down Expand Up @@ -250,7 +250,7 @@ void shouldExportElectronicAddressWithAllFields() {
"Title",
null, null, null,
now,
new DateTimeIntervalDto(now.toEpochSecond(), 3600L),
new CustomerDateTimeIntervalDto(now.toEpochSecond(), 3600L),
"LOAD_MGMT",
false,
null,
Expand Down Expand Up @@ -314,7 +314,7 @@ private CustomerAgreementDto createFullCustomerAgreementDto() {
);

OffsetDateTime validityStart = OffsetDateTime.of(2025, 1, 1, 0, 0, 0, 0, ZoneOffset.UTC);
DateTimeIntervalDto validityInterval = new DateTimeIntervalDto(
CustomerDateTimeIntervalDto validityInterval = new CustomerDateTimeIntervalDto(
validityStart.toEpochSecond(),
31536000L // 1 year in seconds
);
Expand Down
Loading
Loading