diff --git a/CLAUDE.md b/CLAUDE.md
index 0a065dde..ce8ab951 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -129,7 +129,7 @@ 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
@@ -137,7 +137,7 @@ REST controllers are in `openespi-datacustodian/src/main/java/org/greenbuttonall
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`).
@@ -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
diff --git a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/common/DateTimeInterval.java b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/common/DateTimeInterval.java
index af7d178b..7f3d2bd5 100644
--- a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/common/DateTimeInterval.java
+++ b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/common/DateTimeInterval.java
@@ -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.
@@ -41,14 +37,14 @@
*
*
Per ESPI 4.0 espi.xsd lines 1337-1357.
*
+ *
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 ESPI Specification
*/
@Embeddable
-@XmlAccessorType(XmlAccessType.FIELD)
-@XmlType(name = "DateTimeInterval", namespace = "http://naesb.org/espi", propOrder = {
- "duration",
- "start"
-})
@Getter
@Setter
@NoArgsConstructor
@@ -62,7 +58,6 @@ public class DateTimeInterval {
*
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;
@@ -72,7 +67,6 @@ public class DateTimeInterval {
*
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;
diff --git a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/usage/enums/ServiceKind.java b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/usage/enums/ServiceKind.java
index dec2f3d9..02d3c7f9 100644
--- a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/usage/enums/ServiceKind.java
+++ b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/usage/enums/ServiceKind.java
@@ -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;
@@ -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 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();
+ }
}
\ No newline at end of file
diff --git a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/atom/UsageAtomEntryDto.java b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/atom/UsageAtomEntryDto.java
index 89fcb2f9..0b009bd0 100644
--- a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/atom/UsageAtomEntryDto.java
+++ b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/atom/UsageAtomEntryDto.java
@@ -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: (#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"),
diff --git a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/common/DateTimeIntervalDto.java b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/common/DateTimeIntervalDto.java
index 513da1ca..96f3ef93 100644
--- a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/common/DateTimeIntervalDto.java
+++ b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/common/DateTimeIntervalDto.java
@@ -34,11 +34,17 @@
*
* Represents a time interval with start and duration.
* Used in various Green Button resources for time-based data.
+ *
+ * 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
@@ -46,10 +52,10 @@
@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;
/**
diff --git a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerAgreementDto.java b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerAgreementDto.java
index 1ed04db7..aa1a666a 100644
--- a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerAgreementDto.java
+++ b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerAgreementDto.java
@@ -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;
@@ -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) ====================
diff --git a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerDateTimeIntervalDto.java b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerDateTimeIntervalDto.java
new file mode 100644
index 00000000..98eac49d
--- /dev/null
+++ b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerDateTimeIntervalDto.java
@@ -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).
+ *
+ * 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;
+}
diff --git a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/usage/TimeConfigurationDto.java b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/usage/TimeConfigurationDto.java
index 7aea2726..3a18268b 100644
--- a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/usage/TimeConfigurationDto.java
+++ b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/usage/TimeConfigurationDto.java
@@ -36,10 +36,14 @@
* Complies with NAESB ESPI 4.0 XSD specification.
*
* Field order strictly matches espi.xsd TimeConfiguration element sequence.
+ *
+ * The element is {@code espi:LocalTimeParameters}: espi.xsd declares
+ * {@code } and has no global
+ * {@code TimeConfiguration} element, so {@code } fails XSD validation (#279).
*
* @see NAESB ESPI 4.0
*/
-@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",
diff --git a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/mapper/customer/CustomerAgreementMapper.java b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/mapper/customer/CustomerAgreementMapper.java
index 8304fc52..a3d422d3 100644
--- a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/mapper/customer/CustomerAgreementMapper.java
+++ b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/mapper/customer/CustomerAgreementMapper.java
@@ -23,7 +23,6 @@
import org.greenbuttonalliance.espi.common.dto.customer.CustomerAgreementDto;
import org.greenbuttonalliance.espi.common.mapper.BaseMapperUtils;
import org.greenbuttonalliance.espi.common.mapper.DateTimeMapper;
-import org.greenbuttonalliance.espi.common.mapper.usage.DateTimeIntervalMapper;
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
@@ -40,8 +39,7 @@
DateTimeMapper.class,
BaseMapperUtils.class,
ElectronicAddressMapper.class,
- StatusMapper.class,
- DateTimeIntervalMapper.class
+ StatusMapper.class
})
public interface CustomerAgreementMapper {
diff --git a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/mapper/usage/TariffRiderRefMapper.java b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/mapper/usage/TariffRiderRefMapper.java
index f6609997..6e8dc980 100644
--- a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/mapper/usage/TariffRiderRefMapper.java
+++ b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/mapper/usage/TariffRiderRefMapper.java
@@ -94,11 +94,13 @@ default List 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 entities) {
- if (entities == null) {
+ if (entities == null || entities.isEmpty()) {
return null;
}
return new TariffRiderRefsDto(toDtoList(entities));
diff --git a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/service/BaseExportService.java b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/service/BaseExportService.java
index c0d4d684..f26e2d0f 100644
--- a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/service/BaseExportService.java
+++ b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/service/BaseExportService.java
@@ -255,35 +255,74 @@ public void exportFeed(String feedHref, String titl
public AtomFeedDto buildFeed(String feedHref, String title, List entities,
Function super E, ?> toContent) {
Objects.requireNonNull(feedHref, "feedHref");
- OffsetDateTime now = OffsetDateTime.now(ZoneOffset.UTC).truncatedTo(ChronoUnit.SECONDS);
-
- List entries = new ArrayList<>(entities.size());
+ List 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 }, 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 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/}),
+ * 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 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 links = List.of(
- new LinkDto("self", selfHref, "espi-entry/" + entryResource),
- new LinkDto("up", upHref, "espi-feed/" + entryResource));
+ List entries = new ArrayList<>(feedEntries.size());
+ for (FeedEntry feedEntry : feedEntries) {
+ IdentifiedObject entity = feedEntry.entity();
+ String entryResource = resourceName(feedEntry.content());
+ List 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;
}
diff --git a/openespi-common/src/test/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerAgreementDtoTest.java b/openespi-common/src/test/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerAgreementDtoTest.java
index 3275893e..e4b08afc 100644
--- a/openespi-common/src/test/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerAgreementDtoTest.java
+++ b/openespi-common/src/test/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerAgreementDtoTest.java
@@ -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;
@@ -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,
@@ -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
);
diff --git a/openespi-common/src/test/java/org/greenbuttonalliance/espi/common/dto/usage/TimeConfigurationDtoTest.java b/openespi-common/src/test/java/org/greenbuttonalliance/espi/common/dto/usage/TimeConfigurationDtoTest.java
index 2781b968..735767ea 100644
--- a/openespi-common/src/test/java/org/greenbuttonalliance/espi/common/dto/usage/TimeConfigurationDtoTest.java
+++ b/openespi-common/src/test/java/org/greenbuttonalliance/espi/common/dto/usage/TimeConfigurationDtoTest.java
@@ -72,13 +72,12 @@ void shouldMarshalTimeConfigurationWithRealisticData() throws Exception {
String xml = writer.toString();
// Verify XML structure
- assertThat(xml).contains("TimeConfiguration");
- assertThat(xml).contains("http://naesb.org/espi");
+ // espi.xsd's element for a TimeConfiguration is LocalTimeParameters (#279).
// Note: mRID/uuid is handled by Atom wrapper, not the ESPI resource itself
- assertThat(xml).contains("tzOffset"); // Element should be present
- assertThat(xml).contains("-28800"); // Timezone value
- assertThat(xml).contains("dstOffset");
- assertThat(xml).contains("3600");
+ assertThat(xml)
+ .contains(" fb4 =
- AuthorityAuthorizationManager.hasAuthority("FB_4");
+ AuthorityAuthorizationManager.hasAuthority(UsageFunctionBlockAuthorities.INTERVAL_METERING);
AuthorizationManager commodity =
AuthorityAuthorizationManager.hasAnyAuthority(commodityAuthorities());
AuthorizationManager usageData =
@@ -125,10 +123,11 @@ public SecurityFilterChain securityFilterChain(HttpSecurity http,
// Usage summaries (data-shape FBs) and power-quality summary (FB_17).
AuthorizationManager usageSummary =
- AuthorizationManagers.anyOf(admin,
- AuthorityAuthorizationManager.hasAnyAuthority("FB_15", "FB_16", "FB_27", "FB_28"));
+ AuthorizationManagers.anyOf(admin, AuthorityAuthorizationManager.hasAnyAuthority(
+ UsageFunctionBlockAuthorities.USAGE_SUMMARY.toArray(String[]::new)));
AuthorizationManager powerQuality =
- AuthorizationManagers.anyOf(admin, AuthorityAuthorizationManager.hasAuthority("FB_17"));
+ AuthorizationManagers.anyOf(admin, AuthorityAuthorizationManager.hasAnyAuthority(
+ UsageFunctionBlockAuthorities.POWER_QUALITY.toArray(String[]::new)));
// Customer / PII resources — least-privilege per the ESPI Customer-PII catalog: the base
// Connect-My-Data customer FB (FB_53) AND the resource-specific FB, or admin. FB→resource
@@ -193,6 +192,13 @@ public SecurityFilterChain securityFilterChain(HttpSecurity http,
"/espi/1_1/resource/RetailCustomer/*/UsagePoint/*/ElectricPowerQualitySummary/**")
.access(powerQuality)
+ // --- Batch/Subscription (#279): FB_4 + an electricity, gas or water FB (FB_5-FB_11), or admin.
+ // The feed holds only the UsagePoints whose service category a granted FB covers. ---
+ .requestMatchers(HttpMethod.GET, "/espi/1_1/resource/Batch/Subscription/**")
+ .access(AuthorizationManagers.anyOf(admin, AuthorizationManagers.allOf(fb4,
+ AuthorityAuthorizationManager.hasAnyAuthority(
+ UsageFunctionBlockAuthorities.SERVICE_COMMODITY.toArray(String[]::new)))))
+
// --- Usage data (GET, read-only) : FB_4 + commodity, or admin ---
.requestMatchers(HttpMethod.GET,
"/espi/1_1/resource/UsagePoint/**",
@@ -290,10 +296,7 @@ public OpaqueTokenIntrospector introspector() {
* drifts from the spec.
*/
private static String[] commodityAuthorities() {
- return Stream.of(FunctionBlock.values())
- .filter(fb -> fb.getCategory() == FunctionBlockCategory.COMMODITY)
- .map(fb -> "FB_" + fb.getId())
- .toArray(String[]::new);
+ return UsageFunctionBlockAuthorities.COMMODITY.toArray(String[]::new);
}
/**
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java
new file mode 100644
index 00000000..8a79e535
--- /dev/null
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java
@@ -0,0 +1,110 @@
+/*
+ *
+ * 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.datacustodian.config;
+
+import org.greenbuttonalliance.espi.common.domain.usage.enums.ServiceKind;
+import org.greenbuttonalliance.espi.common.scope.FunctionBlock;
+import org.greenbuttonalliance.espi.common.scope.FunctionBlockCategory;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.core.GrantedAuthority;
+
+import java.util.EnumSet;
+import java.util.List;
+import java.util.Set;
+import java.util.stream.Stream;
+
+/**
+ * The Function Block authorities ({@code FB_}, from {@link EspiScopeOpaqueTokenIntrospector}) that grant
+ * each kind of usage data. {@link SecurityConfiguration}'s URL rules and the {@code Batch/Subscription} feed
+ * (#279), which holds several resource types behind one URL, both read them here, so a rule is stated once
+ * until #187's {@code ResourceFbPolicy} replaces them.
+ */
+public final class UsageFunctionBlockAuthorities {
+
+ /** Interval metering: the base for UsagePoint, MeterReading, ReadingType, IntervalBlock, LocalTimeParameters. */
+ public static final String INTERVAL_METERING = "FB_4";
+
+ /** Usage summaries (the data-shape FBs). */
+ public static final List USAGE_SUMMARY = List.of("FB_15", "FB_16", "FB_27", "FB_28");
+
+ /** Power-quality summary. */
+ public static final List POWER_QUALITY = List.of("FB_17");
+
+ /** Every commodity FB (electricity, gas, water, ...): at least one is needed with {@link #INTERVAL_METERING}. */
+ public static final List COMMODITY = Stream.of(FunctionBlock.values())
+ .filter(fb -> fb.getCategory() == FunctionBlockCategory.COMMODITY)
+ .map(fb -> "FB_" + fb.getId())
+ .toList();
+
+ /**
+ * The commodity FBs that cover a UsagePoint service category (FB_5 to FB_9 electricity, FB_10 gas, FB_11
+ * water): one is needed with {@link #INTERVAL_METERING} for {@code Batch/Subscription}. FB_29 (temperature,
+ * no service kind yet: #283) is not one of them.
+ */
+ public static final List SERVICE_COMMODITY = Stream.of(FunctionBlock.values())
+ .filter(fb -> fb.getCategory() == FunctionBlockCategory.COMMODITY && fb.getServiceKind().isPresent())
+ .map(fb -> "FB_" + fb.getId())
+ .toList();
+
+ /**
+ * Every usage-data FB: interval metering, the commodities, the usage summaries and power quality. A scope
+ * with any of them is a usage scope whose {@code HistoryLength} limits usage data.
+ */
+ public static final List USAGE_DATA = Stream.of(
+ List.of(INTERVAL_METERING), COMMODITY, USAGE_SUMMARY, POWER_QUALITY)
+ .flatMap(List::stream)
+ .toList();
+
+ private UsageFunctionBlockAuthorities() {
+ }
+
+ /**
+ * The UsagePoint service kinds the token's commodity Function Blocks grant, from each FB's service kind:
+ * FB_5 to FB_9 grant ELECTRICITY, FB_10 GAS, FB_11 WATER. A commodity FB without a service kind (FB_29,
+ * temperature: #283) grants none, nor does interval metering (FB_4) alone. A UsagePoint's kind is
+ * {@link ServiceKind#of}, the mapping the consent screen uses.
+ */
+ public static Set serviceKinds(Authentication authentication) {
+ Set kinds = EnumSet.noneOf(ServiceKind.class);
+ if (authentication == null) {
+ return kinds;
+ }
+ for (GrantedAuthority granted : authentication.getAuthorities()) {
+ String name = granted.getAuthority();
+ if (name != null && SERVICE_COMMODITY.contains(name)) {
+ FunctionBlock.serviceKindOf(Integer.parseInt(name.substring(3))).ifPresent(kinds::add);
+ }
+ }
+ return kinds;
+ }
+
+ /** Whether the authentication holds at least one of the authorities. */
+ public static boolean hasAny(Authentication authentication, List authorities) {
+ if (authentication == null) {
+ return false;
+ }
+ for (GrantedAuthority granted : authentication.getAuthorities()) {
+ if (authorities.contains(granted.getAuthority())) {
+ return true;
+ }
+ }
+ return false;
+ }
+}
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/sample/LocalSampleDataSeedRunner.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/sample/LocalSampleDataSeedRunner.java
index e6b58a0d..92b38e4c 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/sample/LocalSampleDataSeedRunner.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/sample/LocalSampleDataSeedRunner.java
@@ -305,9 +305,10 @@ private ApplicationInformationEntity sampleThirdPartyApplication() {
app.setContacts("thirdparty@example.com");
app.setTokenEndpointAuthMethod("client_secret_basic");
app.setClientIdIssuedAt(START);
+ // HistoryLength is in seconds (REQ.21.6.1.2.1): 34128000 = 395 days, as in REQ.21.4.2.1.2.1's example.
app.setScope(Set.of(
- "FB=4_5_15;IntervalDuration=3600;BlockDuration=monthly;HistoryLength=13",
- "FB=4_5_15;IntervalDuration=900;BlockDuration=monthly;HistoryLength=13"));
+ "FB=4_5_15;IntervalDuration=3600;BlockDuration=monthly;HistoryLength=34128000",
+ "FB=4_5_15;IntervalDuration=900;BlockDuration=monthly;HistoryLength=34128000"));
app.setGrantTypes(Set.of(GrantType.AUTHORIZATION_CODE, GrantType.REFRESH_TOKEN, GrantType.CLIENT_CREDENTIALS));
app.setResponseTypes(ResponseType.CODE);
return app;
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
new file mode 100644
index 00000000..a3ce3f9c
--- /dev/null
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
@@ -0,0 +1,163 @@
+/*
+ *
+ * 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.datacustodian.web.api;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import org.greenbuttonalliance.espi.common.dto.atom.AtomFeedDto;
+import org.greenbuttonalliance.espi.common.service.impl.UsageExportService;
+import org.greenbuttonalliance.espi.datacustodian.config.UsageFunctionBlockAuthorities;
+import org.greenbuttonalliance.espi.datacustodian.web.api.SubscriptionFeedAssembler.Grants;
+import org.greenbuttonalliance.espi.datacustodian.web.api.SubscriptionFeedAssembler.Range;
+import org.greenbuttonalliance.espi.datacustodian.web.api.scope.ScopeResolver;
+import org.springframework.format.annotation.DateTimeFormat;
+import org.springframework.format.annotation.DateTimeFormat.ISO;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.core.Authentication;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.server.ResponseStatusException;
+import org.springframework.web.servlet.support.ServletUriComponentsBuilder;
+
+import java.io.ByteArrayOutputStream;
+import java.time.Instant;
+import java.time.OffsetDateTime;
+import java.util.UUID;
+
+/**
+ * {@code GET /espi/1_1/resource/Batch/Subscription/{subscriptionId}}: the {@code resourceURI} of a customer
+ * access token (REQ.21 6.1.2), answered with one Atom feed of the subscription's energy usage data (#279).
+ *
+ * Access ({@link ScopeResolver#canReadSubscription}): the DataCustodian admin, or a customer access
+ * token for exactly this subscription. Anything else gets 403, whether or not the subscription exists. The
+ * URL rule in {@code SecurityConfiguration} requires interval metering (FB_4) and an electricity, gas or water
+ * Function Block (FB_5 to FB_11) first. Those commodity Function Blocks decide which UsagePoints the feed holds
+ * (by service category), and the summary Function Blocks which summaries ({@link UsageFunctionBlockAuthorities}).
+ */
+@RestController
+@RequestMapping("/espi/1_1/resource")
+@Tag(name = "Batch", description = "ESPI Batch resource endpoints")
+@SecurityRequirement(name = "oauth2")
+public class BatchSubscriptionController {
+
+ private static final String BATCH_SUBSCRIPTION = "/Batch/Subscription/";
+
+ private final ScopeResolver scopeResolver;
+ private final SubscriptionFeedAssembler assembler;
+ private final UsageExportService usageExportService;
+
+ public BatchSubscriptionController(ScopeResolver scopeResolver, SubscriptionFeedAssembler assembler,
+ UsageExportService usageExportService) {
+ this.scopeResolver = scopeResolver;
+ this.assembler = assembler;
+ this.usageExportService = usageExportService;
+ }
+
+ // No "produces": WebConfiguration's default content type is JSON when a request has no Accept header, so
+ // an XML-only mapping would answer such requests 406. The response is always application/atom+xml.
+ @GetMapping("/Batch/Subscription/{subscriptionId}")
+ @Operation(
+ summary = "Get a Subscription's energy usage data",
+ description = "One Atom feed with the subscription's UsagePoints and their MeterReadings, ReadingTypes,"
+ + " IntervalBlocks, summaries and LocalTimeParameters, as granted by the token's scope",
+ responses = {
+ @ApiResponse(responseCode = "200", description = "The subscription's feed"),
+ @ApiResponse(responseCode = "400",
+ description = "A query parameter is not an xs:dateTime, or a -min is after its -max"),
+ @ApiResponse(responseCode = "401", description = "Unauthorized"),
+ @ApiResponse(responseCode = "403", description = "Not this token's subscription"),
+ @ApiResponse(responseCode = "404", description = "No such subscription (DataCustodian admin only)")
+ }
+ )
+ public ResponseEntity getSubscription(
+ @Parameter(description = "The subscription id from the token's resourceURI", required = true)
+ @PathVariable UUID subscriptionId,
+ @Parameter(description = "Return data whose interval ends after this time (xs:dateTime)."
+ + " Without published-min and published-max: the last 24 hours")
+ @RequestParam(name = "published-min", required = false) @DateTimeFormat(iso = ISO.DATE_TIME)
+ OffsetDateTime publishedMin,
+ @Parameter(description = "Return data whose interval starts at or before this time (xs:dateTime)")
+ @RequestParam(name = "published-max", required = false) @DateTimeFormat(iso = ISO.DATE_TIME)
+ OffsetDateTime publishedMax,
+ @Parameter(description = "Return data whose atom:updated is at or after this time (xs:dateTime)")
+ @RequestParam(name = "updated-min", required = false) @DateTimeFormat(iso = ISO.DATE_TIME)
+ OffsetDateTime updatedMin,
+ @Parameter(description = "Return data whose atom:updated is at or before this time (xs:dateTime)")
+ @RequestParam(name = "updated-max", required = false) @DateTimeFormat(iso = ISO.DATE_TIME)
+ OffsetDateTime updatedMax,
+ Authentication authentication) {
+
+ if (!scopeResolver.canReadSubscription(authentication, subscriptionId)) {
+ throw new ResponseStatusException(HttpStatus.FORBIDDEN);
+ }
+ if (reversed(publishedMin, publishedMax) || reversed(updatedMin, updatedMax)) {
+ throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "A -min query parameter is after its -max");
+ }
+ Range range = new Range(instant(publishedMin), instant(publishedMax), instant(updatedMin), instant(updatedMax));
+ // The self link (and so the feed's UUID v5 id) keeps the query: a different range is a different feed.
+ String feedHref = ServletUriComponentsBuilder.fromCurrentRequest().toUriString();
+ String resourceBase = feedHref.substring(0, feedHref.indexOf(BATCH_SUBSCRIPTION));
+ AtomFeedDto feed = assembler.build(subscriptionId, resourceBase, feedHref, grants(authentication), range)
+ .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND));
+
+ ByteArrayOutputStream out = new ByteArrayOutputStream();
+ usageExportService.exportDto(feed, out);
+ return ResponseEntity.ok()
+ .contentType(MediaType.APPLICATION_ATOM_XML)
+ .body(out.toByteArray());
+ }
+
+ /**
+ * The admin sees everything; a customer token sees what its Function Blocks grant, no further back than its
+ * HistoryLength. An FB scope that does not parse is refused (403) rather than read as "no limit".
+ */
+ private Grants grants(Authentication authentication) {
+ if (scopeResolver.isAdmin(authentication)) {
+ return Grants.all();
+ }
+ Long historyLength;
+ try {
+ historyLength = scopeResolver.historyLengthSeconds(authentication).orElse(null);
+ } catch (IllegalArgumentException ex) {
+ throw new ResponseStatusException(HttpStatus.FORBIDDEN, "Unreadable ESPI scope");
+ }
+ return new Grants(
+ UsageFunctionBlockAuthorities.serviceKinds(authentication),
+ UsageFunctionBlockAuthorities.hasAny(authentication, UsageFunctionBlockAuthorities.USAGE_SUMMARY),
+ UsageFunctionBlockAuthorities.hasAny(authentication, UsageFunctionBlockAuthorities.POWER_QUALITY),
+ historyLength);
+ }
+
+ private static boolean reversed(OffsetDateTime min, OffsetDateTime max) {
+ return min != null && max != null && min.isAfter(max);
+ }
+
+ private static Instant instant(OffsetDateTime time) {
+ return time == null ? null : time.toInstant();
+ }
+}
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
new file mode 100644
index 00000000..278adf8d
--- /dev/null
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
@@ -0,0 +1,353 @@
+/*
+ *
+ * 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.datacustodian.web.api;
+
+import org.greenbuttonalliance.espi.common.domain.common.DateTimeInterval;
+import org.greenbuttonalliance.espi.common.domain.usage.enums.ServiceKind;
+import org.greenbuttonalliance.espi.common.domain.common.IdentifiedObject;
+import org.greenbuttonalliance.espi.common.domain.usage.ElectricPowerQualitySummaryEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.IntervalBlockEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.MeterReadingEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.ReadingTypeEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.SubscriptionEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.TimeConfigurationEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.UsagePointEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.UsageSummaryEntity;
+import org.greenbuttonalliance.espi.common.dto.atom.AtomFeedDto;
+import org.greenbuttonalliance.espi.common.dto.atom.LinkDto;
+import org.greenbuttonalliance.espi.common.mapper.usage.ElectricPowerQualitySummaryMapper;
+import org.greenbuttonalliance.espi.common.mapper.usage.IntervalBlockMapper;
+import org.greenbuttonalliance.espi.common.mapper.usage.MeterReadingMapper;
+import org.greenbuttonalliance.espi.common.mapper.usage.ReadingTypeMapper;
+import org.greenbuttonalliance.espi.common.mapper.usage.TimeConfigurationMapper;
+import org.greenbuttonalliance.espi.common.mapper.usage.UsagePointMapper;
+import org.greenbuttonalliance.espi.common.mapper.usage.UsageSummaryMapper;
+import org.greenbuttonalliance.espi.common.repositories.usage.SubscriptionRepository;
+import org.greenbuttonalliance.espi.common.service.BaseExportService.FeedEntry;
+import org.greenbuttonalliance.espi.common.service.impl.UsageExportService;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.Clock;
+import java.time.Instant;
+import java.time.LocalDateTime;
+import java.time.ZoneOffset;
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+import java.util.UUID;
+import java.util.function.Function;
+
+/**
+ * Builds {@code Batch/Subscription/{subscriptionId}} (#279): one Atom feed with the energy usage data of a
+ * subscription. The caller has already checked who may read it ({@code ScopeResolver#canReadSubscription}).
+ *
+ * UsagePoints: those the customer selected whose {@code ServiceCategory} a granted commodity Function Block
+ * covers (FB_5 to FB_9 electricity, FB_10 gas, FB_11 water; the URL rule requires one of them with FB_4).
+ * Temperature (FB_29) is not yet defined (#283).
+ *
+ * Entries, in the order of certified feeds, for each of those UsagePoints (UsagePoints and MeterReadings
+ * by id, time-bounded resources by interval start):
+ *
+ * - the UsagePoint;
+ * - each MeterReading, its ReadingType (once in the feed, even if shared) and its IntervalBlocks;
+ * - the UsageSummaries and ElectricPowerQualitySummaries, when the token's Function Blocks grant them;
+ * - its LocalTimeParameters (once in the feed, even if shared).
+ *
+ *
+ * Hrefs are subscription-scoped ({@code .../Subscription/{id}/UsagePoint/{id}/...}); ReadingType and
+ * LocalTimeParameters are root resources. Each entry has {@code self} and {@code up}, plus {@code related}
+ * links to the resources it refers to that are in the feed.
+ *
+ * Which IntervalBlocks, UsageSummaries and ElectricPowerQualitySummaries are returned (the "time-bounded"
+ * resources, by their interval, billing period or summary interval, whose end is start + duration):
+ *
+ * - {@code published-min}/{@code published-max} select those whose interval overlaps the range;
+ * - with none of the four range parameters, the default is the last 24 hours, by overlap, plus, for each
+ * UsagePoint, its most
+ * recent UsageSummary and its most recent ElectricPowerQualitySummary (summary intervals rarely line up
+ * with a 24-hour window);
+ * - {@code updated-min}/{@code updated-max} select by {@code atom:updated}; they apply to these
+ * time-bounded resources only, since the UsagePoints, MeterReadings, ReadingTypes and LocalTimeParameters
+ * are the parents the selected entries need;
+ * - {@code HistoryLength} (REQ.21.6.1.2.1: "The amount of historical information available from the Data
+ * Custodian in seconds") is a ceiling, not a selection: nothing that ended before now minus that many
+ * seconds is returned, whatever the range asks for.
+ *
+ * A resource without an interval is kept: there is nothing to measure it against. {@code BlockDuration}
+ * describes the blocks and selects nothing.
+ */
+@Component
+public class SubscriptionFeedAssembler {
+
+ /** The default range when the request has neither {@code published-min} nor {@code published-max}. */
+ static final long DEFAULT_WINDOW_SECONDS = 24 * 60 * 60L;
+
+ /**
+ * What the token grants, beyond reading the subscription at all: the UsagePoint service kinds its
+ * commodity Function Blocks cover, the summaries, and the HistoryLength ceiling in seconds.
+ *
+ * @param serviceKinds null for every UsagePoint (the admin)
+ */
+ public record Grants(Set serviceKinds, boolean usageSummaries,
+ boolean powerQualitySummaries, Long historyLengthSeconds) {
+
+ public static Grants all() {
+ return new Grants(null, true, true, null);
+ }
+
+ boolean covers(UsagePointEntity usagePoint) {
+ return serviceKinds == null
+ || ServiceKind.of(usagePoint.getServiceCategory()).map(serviceKinds::contains).orElse(false);
+ }
+ }
+
+ /** The request's ESPI query parameters (REQ.21.6.2.8); each may be null. */
+ public record Range(Instant publishedMin, Instant publishedMax, Instant updatedMin, Instant updatedMax) {
+
+ public static Range none() {
+ return new Range(null, null, null, null);
+ }
+ }
+
+ private static final Comparator BY_ID = Comparator.comparing(IdentifiedObject::getId);
+
+ private final SubscriptionRepository subscriptionRepository;
+ private final UsageExportService usageExportService;
+ private final UsagePointMapper usagePointMapper;
+ private final MeterReadingMapper meterReadingMapper;
+ private final ReadingTypeMapper readingTypeMapper;
+ private final IntervalBlockMapper intervalBlockMapper;
+ private final UsageSummaryMapper usageSummaryMapper;
+ private final ElectricPowerQualitySummaryMapper powerQualitySummaryMapper;
+ private final TimeConfigurationMapper timeConfigurationMapper;
+ private final Clock clock = Clock.systemUTC();
+
+ public SubscriptionFeedAssembler(SubscriptionRepository subscriptionRepository,
+ UsageExportService usageExportService,
+ UsagePointMapper usagePointMapper,
+ MeterReadingMapper meterReadingMapper,
+ ReadingTypeMapper readingTypeMapper,
+ IntervalBlockMapper intervalBlockMapper,
+ UsageSummaryMapper usageSummaryMapper,
+ ElectricPowerQualitySummaryMapper powerQualitySummaryMapper,
+ TimeConfigurationMapper timeConfigurationMapper) {
+ this.subscriptionRepository = subscriptionRepository;
+ this.usageExportService = usageExportService;
+ this.usagePointMapper = usagePointMapper;
+ this.meterReadingMapper = meterReadingMapper;
+ this.readingTypeMapper = readingTypeMapper;
+ this.intervalBlockMapper = intervalBlockMapper;
+ this.usageSummaryMapper = usageSummaryMapper;
+ this.powerQualitySummaryMapper = powerQualitySummaryMapper;
+ this.timeConfigurationMapper = timeConfigurationMapper;
+ }
+
+ /**
+ * The subscription's feed, or empty if there is no such subscription.
+ *
+ * @param resourceBase the DC's resource base, {@code https://{host}/.../espi/1_1/resource}
+ * @param feedHref the request's absolute URL (the feed's self link)
+ */
+ @Transactional(readOnly = true)
+ public Optional build(UUID subscriptionId, String resourceBase, String feedHref, Grants grants,
+ Range range) {
+ return subscriptionRepository.findById(subscriptionId)
+ .map(subscription -> usageExportService.buildFeedOf(feedHref, "Subscription",
+ "Green Button Subscription Feed",
+ entries(subscription, resourceBase, grants, Selection.of(range, grants, clock.instant()))));
+ }
+
+ private List entries(SubscriptionEntity subscription, String resourceBase, Grants grants,
+ Selection selection) {
+ String subscriptionHref = resourceBase + "/Subscription/" + subscription.getId();
+ Set readingTypesInFeed = new HashSet<>();
+ Set localTimesInFeed = new HashSet<>();
+ List entries = new ArrayList<>();
+
+ List usagePoints = sorted(subscription.getUsagePoints(), BY_ID).stream()
+ .filter(grants::covers)
+ .toList();
+ for (UsagePointEntity usagePoint : usagePoints) {
+ String usagePointFeed = subscriptionHref + "/UsagePoint";
+ String usagePointHref = usagePointFeed + "/" + usagePoint.getId();
+ List summaries = !grants.usageSummaries() ? List.of()
+ : selection.summaries(usagePoint.getUsageSummaries(), UsageSummaryEntity::getBillingPeriod);
+ List qualitySummaries = !grants.powerQualitySummaries() ? List.of()
+ : selection.summaries(usagePoint.getElectricPowerQualitySummaries(),
+ ElectricPowerQualitySummaryEntity::getSummaryInterval);
+ TimeConfigurationEntity localTime = usagePoint.getLocalTimeParameters();
+
+ List usagePointRelated = new ArrayList<>();
+ if (!usagePoint.getMeterReadings().isEmpty()) {
+ usagePointRelated.add(related(usagePointHref + "/MeterReading", "espi-feed/MeterReading"));
+ }
+ if (!summaries.isEmpty()) {
+ usagePointRelated.add(related(usagePointHref + "/UsageSummary", "espi-feed/UsageSummary"));
+ }
+ if (!qualitySummaries.isEmpty()) {
+ usagePointRelated.add(related(usagePointHref + "/ElectricPowerQualitySummary",
+ "espi-feed/ElectricPowerQualitySummary"));
+ }
+ if (localTime != null) {
+ usagePointRelated.add(related(resourceBase + "/LocalTimeParameters/" + localTime.getId(),
+ "espi-entry/LocalTimeParameters"));
+ }
+ entries.add(new FeedEntry(usagePoint, usagePointMapper.toDto(usagePoint), usagePointHref,
+ usagePointFeed, usagePointRelated));
+
+ for (MeterReadingEntity meterReading : sorted(usagePoint.getMeterReadings(), BY_ID)) {
+ addMeterReading(entries, meterReading, usagePointHref, resourceBase, selection, readingTypesInFeed);
+ }
+ for (UsageSummaryEntity summary : summaries) {
+ String feed = usagePointHref + "/UsageSummary";
+ entries.add(new FeedEntry(summary, usageSummaryMapper.toDto(summary), feed + "/" + summary.getId(),
+ feed, List.of()));
+ }
+ for (ElectricPowerQualitySummaryEntity summary : qualitySummaries) {
+ String feed = usagePointHref + "/ElectricPowerQualitySummary";
+ entries.add(new FeedEntry(summary, powerQualitySummaryMapper.toDto(summary),
+ feed + "/" + summary.getId(), feed, List.of()));
+ }
+ if (localTime != null && localTimesInFeed.add(localTime.getId())) {
+ String feed = resourceBase + "/LocalTimeParameters";
+ entries.add(new FeedEntry(localTime, timeConfigurationMapper.toDto(localTime),
+ feed + "/" + localTime.getId(), feed, List.of()));
+ }
+ }
+ return entries;
+ }
+
+ private void addMeterReading(List entries, MeterReadingEntity meterReading, String usagePointHref,
+ String resourceBase, Selection selection, Set readingTypesInFeed) {
+ String meterReadingFeed = usagePointHref + "/MeterReading";
+ String meterReadingHref = meterReadingFeed + "/" + meterReading.getId();
+ ReadingTypeEntity readingType = meterReading.getReadingType();
+ List blocks = selection.blocks(meterReading.getIntervalBlocks());
+
+ List meterReadingRelated = new ArrayList<>();
+ if (readingType != null) {
+ meterReadingRelated.add(related(resourceBase + "/ReadingType/" + readingType.getId(), "espi-entry/ReadingType"));
+ }
+ if (!blocks.isEmpty()) {
+ meterReadingRelated.add(related(meterReadingHref + "/IntervalBlock", "espi-feed/IntervalBlock"));
+ }
+ entries.add(new FeedEntry(meterReading, meterReadingMapper.toDto(meterReading), meterReadingHref,
+ meterReadingFeed, meterReadingRelated));
+
+ if (readingType != null && readingTypesInFeed.add(readingType.getId())) {
+ String feed = resourceBase + "/ReadingType";
+ entries.add(new FeedEntry(readingType, readingTypeMapper.toDto(readingType),
+ feed + "/" + readingType.getId(), feed, List.of()));
+ }
+ for (IntervalBlockEntity block : blocks) {
+ String feed = meterReadingHref + "/IntervalBlock";
+ entries.add(new FeedEntry(block, intervalBlockMapper.toDto(block), feed + "/" + block.getId(), feed,
+ List.of()));
+ }
+ }
+
+ private static List sorted(List items, Comparator super T> order) {
+ return items == null ? List.of() : items.stream().sorted(order).toList();
+ }
+
+ private static LinkDto related(String href, String type) {
+ return new LinkDto("related", href, type);
+ }
+
+ /**
+ * Which time-bounded resources a request gets, in epoch seconds. {@code from}/{@code to} bound the overlap
+ * (null = open); {@code ceiling} is now minus {@code HistoryLength} seconds (null = no limit).
+ */
+ private record Selection(Long from, Long to, Long ceiling, Long updatedMin, Long updatedMax,
+ boolean defaultWindow) {
+
+ static Selection of(Range range, Grants grants, Instant now) {
+ long nowSeconds = now.getEpochSecond();
+ Long ceiling = grants.historyLengthSeconds() == null ? null : nowSeconds - grants.historyLengthSeconds();
+ // The 24-hour default only when the request gives no range at all: an updated-min/max poll for
+ // corrections must reach data of any age (still under the HistoryLength ceiling).
+ boolean defaultWindow = range.publishedMin() == null && range.publishedMax() == null
+ && range.updatedMin() == null && range.updatedMax() == null;
+ Long from = defaultWindow ? Long.valueOf(nowSeconds - DEFAULT_WINDOW_SECONDS) : seconds(range.publishedMin());
+ return new Selection(from, defaultWindow ? null : seconds(range.publishedMax()), ceiling,
+ seconds(range.updatedMin()), seconds(range.updatedMax()), defaultWindow);
+ }
+
+ /** The blocks in the range, by interval start. */
+ List blocks(List blocks) {
+ return available(blocks, IntervalBlockEntity::getInterval).stream()
+ .filter(block -> overlaps(block.getInterval()))
+ .toList();
+ }
+
+ /** The summaries in the range, by interval start; by default also the most recent one available. */
+ List summaries(List summaries, Function interval) {
+ List available = available(summaries, interval);
+ List selected = new ArrayList<>(available.stream().filter(s -> overlaps(interval.apply(s))).toList());
+ if (defaultWindow && !available.isEmpty() && !selected.contains(available.getLast())) {
+ selected.add(available.getLast());
+ }
+ return selected;
+ }
+
+ /** Within HistoryLength and the updated-min/max range, sorted by interval start (no interval first). */
+ private List available(List items, Function interval) {
+ Comparator byStart = Comparator.comparing(item -> start(interval.apply(item)),
+ Comparator.nullsFirst(Comparator.naturalOrder()));
+ return sorted(items, byStart.thenComparing(IdentifiedObject::getId)).stream()
+ .filter(item -> endsAfter(interval.apply(item), ceiling) && updatedInRange(item.getUpdated()))
+ .toList();
+ }
+
+ private boolean overlaps(DateTimeInterval interval) {
+ if (start(interval) == null) {
+ return true;
+ }
+ return endsAfter(interval, from) && (to == null || interval.getStart() <= to);
+ }
+
+ private boolean updatedInRange(LocalDateTime updated) {
+ if (updated == null) {
+ return updatedMin == null && updatedMax == null;
+ }
+ long seconds = updated.toEpochSecond(ZoneOffset.UTC);
+ return (updatedMin == null || seconds >= updatedMin) && (updatedMax == null || seconds <= updatedMax);
+ }
+
+ private static boolean endsAfter(DateTimeInterval interval, Long limit) {
+ if (limit == null || start(interval) == null) {
+ return true;
+ }
+ return interval.getStart() + (interval.getDuration() == null ? 0 : interval.getDuration()) > limit;
+ }
+
+ private static Long start(DateTimeInterval interval) {
+ return interval == null ? null : interval.getStart();
+ }
+
+ private static Long seconds(Instant instant) {
+ return instant == null ? null : instant.getEpochSecond();
+ }
+ }
+}
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java
index 6862fca5..97a706b0 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java
@@ -19,13 +19,21 @@
package org.greenbuttonalliance.espi.datacustodian.web.api.scope;
import org.greenbuttonalliance.espi.common.repositories.usage.SubscriptionRepository;
+import org.greenbuttonalliance.espi.common.scope.EspiScope;
import org.greenbuttonalliance.espi.common.uri.EspiBatchUri;
+import org.greenbuttonalliance.espi.datacustodian.config.EspiScopeOpaqueTokenIntrospector;
+import org.greenbuttonalliance.espi.datacustodian.config.UsageFunctionBlockAuthorities;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.oauth2.core.OAuth2AuthenticatedPrincipal;
import org.springframework.stereotype.Component;
+import java.util.ArrayList;
+import java.util.Collection;
import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Objects;
+import java.util.Optional;
import java.util.Set;
import java.util.UUID;
@@ -110,15 +118,93 @@ public ResourceScope resolve(Authentication authentication) {
return ResourceScope.of(usagePointIds, retailCustomerIds);
}
- private boolean hasAdminAuthority(Authentication authentication) {
+ /**
+ * Whether the caller may read {@code Batch/Subscription/{subscriptionId}} (#279): the DataCustodian
+ * admin, or a customer access token whose introspected {@code resourceURI} names exactly this
+ * subscription. A Third Party's client access token ({@code FB=34_35}) never may, whatever its URIs: it
+ * is for Authorization and Bulk. Unknown and foreign subscriptions are answered alike, so the caller
+ * learns nothing about subscriptions it does not hold.
+ */
+ public boolean canReadSubscription(Authentication authentication, UUID subscriptionId) {
+ if (subscriptionId == null || authentication == null || !authentication.isAuthenticated()) {
+ return false;
+ }
+ if (hasAdminAuthority(authentication)) {
+ return true;
+ }
+ if (hasAuthority(authentication, EspiScopeOpaqueTokenIntrospector.CLIENT_ACCESS_TOKEN)
+ || !(authentication.getPrincipal() instanceof OAuth2AuthenticatedPrincipal principal)) {
+ return false;
+ }
+ String resourceUri = stringAttribute(principal, "resourceURI");
+ return resourceUri != null && EspiBatchUri.subscriptionId(resourceUri)
+ .flatMap(ScopeResolver::parseUuid)
+ .filter(subscriptionId::equals)
+ .isPresent();
+ }
+
+ /**
+ * Every ESPI scope of the token (each {@code FB=...} scope string, with its {@code HistoryLength} and other
+ * terms), except the client access token's {@code FB=34_35}; empty for a token without one.
+ *
+ * @throws IllegalArgumentException if an FB scope does not parse: the caller must refuse the request rather
+ * than read it as "no limits" (fail closed)
+ */
+ public List espiScopes(Authentication authentication) {
+ if (authentication == null || !(authentication.getPrincipal() instanceof OAuth2AuthenticatedPrincipal principal)) {
+ return List.of();
+ }
+ Object scope = principal.getAttribute("scope");
+ Collection> scopes = scope instanceof Collection> collection ? collection
+ : scope instanceof String s ? List.of(s.trim().split("\\s+")) : List.of();
+ List parsed = new ArrayList<>();
+ for (Object value : scopes) {
+ String text = value == null ? "" : value.toString().trim();
+ if (text.regionMatches(true, 0, "FB=", 0, 3)
+ && !EspiScopeOpaqueTokenIntrospector.CLIENT_ACCESS_TOKEN_SCOPE.equalsIgnoreCase(text)) {
+ parsed.add(EspiScope.parse(text));
+ }
+ }
+ return parsed;
+ }
+
+ /**
+ * The {@code HistoryLength} of the token's usage-data scopes, in seconds (REQ.21.6.1.2.1: "The amount of
+ * historical information available from the Data Custodian in seconds"): the shortest among its FB scopes
+ * that grant any usage-data Function Block (interval metering, a commodity, a usage summary or power
+ * quality), or empty if none states one. Only a scope with no usage-data FB, such as a customer-data scope
+ * ({@code FB=51_53_54;HistoryLength=...}), is left out: it does not limit usage data.
+ *
+ * @throws IllegalArgumentException if an FB scope does not parse (see {@link #espiScopes})
+ */
+ public Optional historyLengthSeconds(Authentication authentication) {
+ return espiScopes(authentication).stream()
+ .filter(scope -> scope.functionBlocks().stream()
+ .anyMatch(fb -> UsageFunctionBlockAuthorities.USAGE_DATA.contains("FB_" + fb)))
+ .map(EspiScope::historyLength)
+ .filter(Objects::nonNull)
+ .map(Integer::longValue)
+ .min(Long::compare);
+ }
+
+ /** Whether the caller holds the DataCustodian admin authority. */
+ public boolean isAdmin(Authentication authentication) {
+ return authentication != null && hasAdminAuthority(authentication);
+ }
+
+ private static boolean hasAuthority(Authentication authentication, String name) {
for (GrantedAuthority authority : authentication.getAuthorities()) {
- if (ADMIN_AUTHORITY.equals(authority.getAuthority())) {
+ if (name.equals(authority.getAuthority())) {
return true;
}
}
return false;
}
+ private static boolean hasAdminAuthority(Authentication authentication) {
+ return hasAuthority(authentication, ADMIN_AUTHORITY);
+ }
+
private static String stringAttribute(OAuth2AuthenticatedPrincipal principal, String name) {
Object value = principal.getAttribute(name);
if (value == null) {
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/authorize/AuthorizeScreenService.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/authorize/AuthorizeScreenService.java
index 3dfe0b83..86b80de2 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/authorize/AuthorizeScreenService.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/authorize/AuthorizeScreenService.java
@@ -314,13 +314,7 @@ private static String rebuildScope(EspiScope original, Set keptFbs) {
}
private static ServiceKind toServiceKind(ServiceCategory category) {
- if (category == null) return null;
- try {
- return ServiceKind.valueOf(category.name());
- }
- catch (IllegalArgumentException e) {
- return null;
- }
+ return ServiceKind.of(category).orElse(null);
}
private static List sortedKinds(Set kinds) {
diff --git a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
new file mode 100644
index 00000000..6f76f545
--- /dev/null
+++ b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
@@ -0,0 +1,597 @@
+/*
+ *
+ * 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.datacustodian.web.api;
+
+import org.greenbuttonalliance.espi.common.domain.common.DateTimeInterval;
+import org.greenbuttonalliance.espi.common.domain.common.ServiceCategory;
+import org.greenbuttonalliance.espi.common.domain.common.enums.GrantType;
+import org.greenbuttonalliance.espi.common.domain.usage.ApplicationInformationEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.AuthorizationEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.RetailCustomerEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.ElectricPowerQualitySummaryEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.IntervalBlockEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.IntervalReadingEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.MeterReadingEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.ReadingTypeEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.SubscriptionEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.TimeConfigurationEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.UsagePointEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.UsageSummaryEntity;
+import org.greenbuttonalliance.espi.common.repositories.usage.ApplicationInformationRepository;
+import org.greenbuttonalliance.espi.common.repositories.usage.AuthorizationRepository;
+import org.greenbuttonalliance.espi.common.repositories.usage.RetailCustomerRepository;
+import org.greenbuttonalliance.espi.common.repositories.usage.SubscriptionRepository;
+import org.greenbuttonalliance.espi.common.repositories.usage.UsagePointRepository;
+import org.greenbuttonalliance.espi.common.xml.EspiXmlSchemaValidator;
+import org.greenbuttonalliance.espi.datacustodian.config.EspiScopeOpaqueTokenIntrospector;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc;
+import org.springframework.security.core.GrantedAuthority;
+import org.springframework.security.core.authority.SimpleGrantedAuthority;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.request.MockHttpServletRequestBuilder;
+import org.springframework.test.web.servlet.request.RequestPostProcessor;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+import java.util.UUID;
+import java.util.regex.Pattern;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.opaqueToken;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/**
+ * {@code GET /Batch/Subscription/{id}} (#279) with real data, the real export service and the real security
+ * rules: exactly the token's subscription, its Function Blocks and HistoryLength, and an XSD-valid feed.
+ */
+@SpringBootTest
+@AutoConfigureMockMvc
+@ActiveProfiles("test")
+@Transactional
+@DisplayName("Batch/Subscription feed (#279)")
+class BatchSubscriptionIntegrationTest {
+
+ private static final String BASE = "http://localhost/espi/1_1/resource";
+ private static final long DAY = 86_400L;
+ /** Interval metering + interval electricity metering: the URL rule's minimum for Batch. */
+ private static final String[] ENERGY_FBS = {"FB_4", "FB_5"};
+
+ private static final UUID SUBSCRIPTION_A = UUID.fromString("3c9d0e6b-6a56-5f11-9a3e-0d1c3b1c2a01");
+ private static final UUID SUBSCRIPTION_B = UUID.fromString("3c9d0e6b-6a56-5f11-9a3e-0d1c3b1c2a02");
+ private static final UUID EMPTY_SUBSCRIPTION = UUID.fromString("3c9d0e6b-6a56-5f11-9a3e-0d1c3b1c2a03");
+ private static final UUID USAGE_POINT_A = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f501");
+ private static final UUID USAGE_POINT_B = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f502");
+ private static final UUID METER_READING_A = UUID.fromString("41a6bd77-3d03-59c4-9ab2-65f2cb09b101");
+ private static final UUID READING_TYPE_A = UUID.fromString("6a4ad1c1-8f0b-5d55-a0a0-2d1c3e4f5a01");
+ private static final UUID RECENT_BLOCK = UUID.fromString("7b5be2d2-9a1c-5e66-b1b1-3e2d4f5a6b01");
+ private static final UUID OLD_BLOCK = UUID.fromString("7b5be2d2-9a1c-5e66-b1b1-3e2d4f5a6b02");
+ private static final UUID USAGE_SUMMARY_A = UUID.fromString("8c6cf3e3-ab2d-5f77-82c2-4f3e5a6b7c01");
+ private static final UUID QUALITY_SUMMARY_A = UUID.fromString("9d7d04f4-bc3e-5088-93d3-504f6b7c8d01");
+ private static final UUID OLD_USAGE_SUMMARY = UUID.fromString("8c6cf3e3-ab2d-5f77-82c2-4f3e5a6b7c02");
+ private static final UUID OLD_QUALITY_SUMMARY = UUID.fromString("9d7d04f4-bc3e-5088-93d3-504f6b7c8d02");
+ private static final UUID LOCAL_TIME_A = UUID.fromString("ae8e1505-cd4f-5199-a4e4-61507c8d9e01");
+ private static final UUID SHARED_SUBSCRIPTION = UUID.fromString("3c9d0e6b-6a56-5f11-9a3e-0d1c3b1c2a04");
+ private static final UUID SHARED_POINT_1 = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f503");
+ private static final UUID SHARED_POINT_2 = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f504");
+ private static final UUID SHARED_LOCAL_TIME = UUID.fromString("ae8e1505-cd4f-5199-a4e4-61507c8d9e02");
+ private static final UUID MIXED_SUBSCRIPTION = UUID.fromString("3c9d0e6b-6a56-5f11-9a3e-0d1c3b1c2a05");
+ private static final UUID ELECTRIC_POINT = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f505");
+ private static final UUID GAS_POINT = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f506");
+ private static final UUID WATER_POINT = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f507");
+ private static final UUID LATEST_SUBSCRIPTION = UUID.fromString("3c9d0e6b-6a56-5f11-9a3e-0d1c3b1c2a06");
+ private static final UUID LATEST_POINT = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f508");
+ private static final UUID LATEST_QUALITY = UUID.fromString("9d7d04f4-bc3e-5088-93d3-504f6b7c8d03");
+
+ /** When the fixtures were made, in epoch seconds. */
+ private long now;
+
+ @Autowired
+ private MockMvc mockMvc;
+
+ @Autowired
+ private AuthorizationRepository authorizationRepository;
+
+ @Autowired
+ private RetailCustomerRepository retailCustomerRepository;
+
+ @Autowired
+ private ApplicationInformationRepository applicationInformationRepository;
+
+ @Autowired
+ private SubscriptionRepository subscriptionRepository;
+
+ @Autowired
+ private UsagePointRepository usagePointRepository;
+
+ @BeforeEach
+ void setUp() {
+ now = Instant.now().getEpochSecond();
+ UsagePointEntity usagePointA = usagePointRepository.save(usagePointA(now));
+ UsagePointEntity usagePointB = new UsagePointEntity();
+ usagePointB.setId(USAGE_POINT_B);
+ usagePointB.setDescription("Another customer's meter");
+ usagePointB.setServiceCategory(ServiceCategory.ELECTRICITY);
+ usagePointB = usagePointRepository.save(usagePointB);
+
+ subscriptionRepository.save(subscription(SUBSCRIPTION_A, List.of(usagePointA)));
+ subscriptionRepository.save(subscription(SUBSCRIPTION_B, List.of(usagePointB)));
+ subscriptionRepository.saveAndFlush(subscription(EMPTY_SUBSCRIPTION, List.of()));
+ }
+
+ @Test
+ @DisplayName("without query parameters: the last 24 hours, plus the latest summaries, in certified order, as valid ESPI XML")
+ void customer_token_gets_its_subscription() throws Exception {
+ String xml = fetch(SUBSCRIPTION_A, customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17", "FB_16", "FB_17"));
+ String subscription = BASE + "/Subscription/" + SUBSCRIPTION_A;
+ String usagePoint = subscription + "/UsagePoint/" + USAGE_POINT_A;
+ String meterReading = usagePoint + "/MeterReading/" + METER_READING_A;
+
+ assertThat(xml)
+ .contains("rel=\"self\" href=\"" + BASE + "/Batch/Subscription/" + SUBSCRIPTION_A
+ + "\" type=\"espi-feed/Subscription\"")
+ .contains("href=\"" + usagePoint + "\" type=\"espi-entry/UsagePoint\"",
+ "rel=\"up\" href=\"" + subscription + "/UsagePoint\" type=\"espi-feed/UsagePoint\"",
+ "rel=\"related\" href=\"" + usagePoint + "/MeterReading\" type=\"espi-feed/MeterReading\"",
+ "rel=\"related\" href=\"" + BASE + "/LocalTimeParameters/" + LOCAL_TIME_A
+ + "\" type=\"espi-entry/LocalTimeParameters\"")
+ .contains("href=\"" + meterReading + "\" type=\"espi-entry/MeterReading\"",
+ "rel=\"related\" href=\"" + BASE + "/ReadingType/" + READING_TYPE_A
+ + "\" type=\"espi-entry/ReadingType\"",
+ "href=\"" + meterReading + "/IntervalBlock/" + RECENT_BLOCK + "\" type=\"espi-entry/IntervalBlock\"",
+ "href=\"" + usagePoint + "/UsageSummary/" + USAGE_SUMMARY_A + "\"",
+ "href=\"" + usagePoint + "/ElectricPowerQualitySummary/" + QUALITY_SUMMARY_A + "\"",
+ "")
+ .doesNotContain(USAGE_POINT_B.toString(), "", "xsi:type", OLD_BLOCK.toString(),
+ OLD_USAGE_SUMMARY.toString(), OLD_QUALITY_SUMMARY.toString());
+ // The UsageSummary's billing period runs to now (overlap); the power quality summary ended 5 days ago and
+ // is there as the UsagePoint's latest.
+ assertThat(entryResources(xml)).containsExactly("UsagePoint", "MeterReading", "ReadingType",
+ "IntervalBlock", "UsageSummary", "ElectricPowerQualitySummary", "LocalTimeParameters");
+ assertValid(xml);
+ }
+
+ @Test
+ @DisplayName("published-min/max select by interval overlap, with no latest-summary exception")
+ void published_range_selects_by_interval() throws Exception {
+ String xml = fetch(SUBSCRIPTION_A, customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17", "FB_16", "FB_17"),
+ "published-min", ago(100 * DAY), "published-max", ago(70 * DAY));
+
+ assertThat(xml)
+ .contains(OLD_USAGE_SUMMARY.toString(), OLD_QUALITY_SUMMARY.toString())
+ .doesNotContain(RECENT_BLOCK.toString(), OLD_BLOCK.toString(), USAGE_SUMMARY_A.toString(),
+ QUALITY_SUMMARY_A.toString());
+ assertValid(xml);
+ }
+
+ @Test
+ @DisplayName("a wide range returns every block and summary, sorted by interval start")
+ void entries_are_chronological() throws Exception {
+ String xml = fetch(SUBSCRIPTION_A, customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17", "FB_16", "FB_17"),
+ "published-min", ago(100 * DAY));
+
+ // The fixtures add the newer one first.
+ assertThat(List.of(
+ xml.indexOf(OLD_BLOCK.toString()) < xml.indexOf(RECENT_BLOCK.toString()),
+ xml.indexOf(OLD_USAGE_SUMMARY.toString()) < xml.indexOf(USAGE_SUMMARY_A.toString()),
+ xml.indexOf(OLD_QUALITY_SUMMARY.toString()) < xml.indexOf(QUALITY_SUMMARY_A.toString())))
+ .containsOnly(true);
+ assertThat(entryResources(xml)).containsExactly("UsagePoint", "MeterReading", "ReadingType",
+ "IntervalBlock", "IntervalBlock", "UsageSummary", "UsageSummary", "ElectricPowerQualitySummary",
+ "ElectricPowerQualitySummary", "LocalTimeParameters");
+ assertValid(xml);
+ }
+
+ @Test
+ @DisplayName("updated-min/max select by atom:updated")
+ void updated_range_selects_by_atom_updated() throws Exception {
+ String xml = fetch(SUBSCRIPTION_A, customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17", "FB_16", "FB_17"),
+ "published-min", ago(100 * DAY), "updated-max", "2000-01-01T00:00:00Z");
+
+ assertThat(entryResources(xml)).containsExactly("UsagePoint", "MeterReading", "ReadingType",
+ "LocalTimeParameters");
+ }
+
+ @Test
+ @DisplayName("updated-min alone drops the 24-hour default, and the query is part of the feed's self link")
+ void updated_min_alone_reaches_older_data() throws Exception {
+ // In the URL, as a client sends it (MockMvc's param() would not set the query string).
+ String xml = mockMvc.perform(get(BASE + "/Batch/Subscription/" + SUBSCRIPTION_A
+ + "?updated-min=2000-01-01T00:00:00Z")
+ .with(customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17", "FB_16", "FB_17")))
+ .andExpect(status().isOk())
+ .andReturn().getResponse().getContentAsString();
+
+ assertThat(xml)
+ .contains(OLD_BLOCK.toString(), RECENT_BLOCK.toString(), OLD_USAGE_SUMMARY.toString(),
+ OLD_QUALITY_SUMMARY.toString())
+ .contains("href=\"" + BASE + "/Batch/Subscription/" + SUBSCRIPTION_A + "?updated-min=");
+ assertValid(xml);
+ }
+
+ @Test
+ @DisplayName("a query parameter that is not an xs:dateTime is a 400")
+ void malformed_query_parameter_is_bad_request() throws Exception {
+ mockMvc.perform(get(BASE + "/Batch/Subscription/" + SUBSCRIPTION_A)
+ .param("published-min", "yesterday")
+ .with(customer(SUBSCRIPTION_A, "FB=1_3_4_5")))
+ .andExpect(status().isBadRequest());
+ }
+
+ @Test
+ @DisplayName("without FB_16 and FB_17 there are no summaries, and no related links to them")
+ void summaries_need_their_function_blocks() throws Exception {
+ String xml = fetch(SUBSCRIPTION_A, customer(SUBSCRIPTION_A, "FB=1_3_4_5"));
+
+ assertThat(xml)
+ .doesNotContain(" usagePoints = new ArrayList<>();
+ for (UsagePointEntity usagePoint : List.of(
+ usagePoint(ELECTRIC_POINT, ServiceCategory.ELECTRICITY),
+ usagePoint(GAS_POINT, ServiceCategory.GAS),
+ usagePoint(WATER_POINT, ServiceCategory.WATER))) {
+ usagePoints.add(usagePointRepository.save(usagePoint));
+ }
+ subscriptionRepository.saveAndFlush(subscription(MIXED_SUBSCRIPTION, usagePoints));
+
+ String electricity = fetch(MIXED_SUBSCRIPTION, token(MIXED_SUBSCRIPTION, "FB=1_3_4_5", "FB_4", "FB_5"));
+ String gasAndWater = fetch(MIXED_SUBSCRIPTION,
+ token(MIXED_SUBSCRIPTION, "FB=1_3_4_10_11", "FB_4", "FB_10", "FB_11"));
+
+ assertThat(electricity).contains(ELECTRIC_POINT.toString())
+ .doesNotContain(GAS_POINT.toString(), WATER_POINT.toString());
+ assertThat(gasAndWater).contains(GAS_POINT.toString(), WATER_POINT.toString())
+ .doesNotContain(ELECTRIC_POINT.toString());
+ assertValid(gasAndWater);
+ // FB_4 alone, FB_4 with only temperature (FB_29, #283), and a commodity FB without FB_4 are refused.
+ for (RequestPostProcessor refused : List.of(
+ token(MIXED_SUBSCRIPTION, "FB=1_3_4", "FB_4"),
+ token(MIXED_SUBSCRIPTION, "FB=1_3_4_29", "FB_4", "FB_29"),
+ token(MIXED_SUBSCRIPTION, "FB=1_3_5", "FB_5"))) {
+ mockMvc.perform(get(BASE + "/Batch/Subscription/" + MIXED_SUBSCRIPTION).with(refused))
+ .andExpect(status().isForbidden());
+ }
+ assertThat(fetch(MIXED_SUBSCRIPTION, admin()))
+ .contains(ELECTRIC_POINT.toString(), GAS_POINT.toString(), WATER_POINT.toString());
+ }
+
+ @Test
+ @DisplayName("a LocalTimeParameters shared by two UsagePoints is one entry, linked from both")
+ void shared_local_time_parameters_is_one_entry() throws Exception {
+ TimeConfigurationEntity shared = localTime(SHARED_LOCAL_TIME);
+ List usagePoints = new ArrayList<>();
+ for (UUID id : List.of(SHARED_POINT_1, SHARED_POINT_2)) {
+ UsagePointEntity usagePoint = usagePoint(id, ServiceCategory.ELECTRICITY);
+ usagePoint.setLocalTimeParameters(shared);
+ usagePoints.add(usagePointRepository.save(usagePoint));
+ }
+ subscriptionRepository.saveAndFlush(subscription(SHARED_SUBSCRIPTION, usagePoints));
+
+ String xml = fetch(SHARED_SUBSCRIPTION, admin());
+
+ // It closes the first UsagePoint's group; the second UsagePoint only links to it.
+ assertThat(entryResources(xml)).containsExactly("UsagePoint", "LocalTimeParameters", "UsagePoint");
+ assertThat(Pattern.compile("rel=\"related\" href=\"" + BASE + "/LocalTimeParameters/" + SHARED_LOCAL_TIME)
+ .matcher(xml).results().count()).isEqualTo(2);
+ assertValid(xml);
+ }
+
+ @Test
+ @DisplayName("a token for subscription A gets 403 for B and for an unknown subscription, alike")
+ void other_subscriptions_are_forbidden() throws Exception {
+ RequestPostProcessor tokenA = customer(SUBSCRIPTION_A, "FB=1_3_4_5");
+
+ mockMvc.perform(get(BASE + "/Batch/Subscription/" + SUBSCRIPTION_B).with(tokenA))
+ .andExpect(status().isForbidden());
+ mockMvc.perform(get(BASE + "/Batch/Subscription/" + UUID.randomUUID()).with(tokenA))
+ .andExpect(status().isForbidden());
+ }
+
+ @Test
+ @DisplayName("a Third Party's client access token is refused, even with energy FBs and a matching resourceURI")
+ void client_access_token_is_refused() throws Exception {
+ RequestPostProcessor clientToken = opaqueToken()
+ .attributes(attributes -> attributes.put("resourceURI", BASE + "/Batch/Subscription/" + SUBSCRIPTION_A))
+ .authorities(authorities(EspiScopeOpaqueTokenIntrospector.CLIENT_ACCESS_TOKEN, "FB_4", "FB_5"));
+
+ mockMvc.perform(get(BASE + "/Batch/Subscription/" + SUBSCRIPTION_A).with(clientToken))
+ .andExpect(status().isForbidden());
+ }
+
+ @Test
+ @DisplayName("the DataCustodian admin reads any subscription, and gets 404 for an unknown one")
+ void admin_reads_any_subscription() throws Exception {
+ assertThat(fetch(SUBSCRIPTION_B, admin())).contains(USAGE_POINT_B.toString())
+ .doesNotContain(USAGE_POINT_A.toString());
+ mockMvc.perform(get(BASE + "/Batch/Subscription/" + UUID.randomUUID()).with(admin()))
+ .andExpect(status().isNotFound());
+ }
+
+ @Test
+ @DisplayName("a subscription with no UsagePoints is a valid empty feed, typed espi-feed/Subscription")
+ void empty_subscription_is_an_empty_feed() throws Exception {
+ String xml = fetch(EMPTY_SUBSCRIPTION, customer(EMPTY_SUBSCRIPTION, "FB=1_3_4_5"));
+
+ assertThat(xml)
+ .contains("href=\"" + BASE + "/Batch/Subscription/" + EMPTY_SUBSCRIPTION + "\" type=\"espi-feed/Subscription\"")
+ .doesNotContain(" entryResources(String xml) {
+ return Pattern.compile("rel=\"self\" href=\"[^\"]*\" type=\"espi-entry/(\\w+)\"").matcher(xml)
+ .results().map(match -> match.group(1)).toList();
+ }
+
+ /**
+ * Valid against atom.xsd + espi.xsd, apart from #278: ServiceCategory is written as the Java constant
+ * name ({@code ELECTRICITY}) instead of espi.xsd's {@code 0}. Remove the exception with #278.
+ */
+ private static void assertValid(String xml) {
+ EspiXmlSchemaValidator.Result result = EspiXmlSchemaValidator.instance().validate(xml);
+ assertThat(result.issues())
+ .as(String.join("\n", EspiXmlSchemaValidator.describe(result)))
+ .filteredOn(issue -> issue.severity() != EspiXmlSchemaValidator.Severity.WARNING)
+ .allSatisfy(issue -> assertThat(issue.message()).contains("ServiceCategory"));
+ }
+
+ /** A customer access token for the subscription, with interval metering + electricity and the extra FBs. */
+ private static RequestPostProcessor customer(UUID subscriptionId, String scope, String... extraFbs) {
+ String[] fbs = Arrays.copyOf(ENERGY_FBS, ENERGY_FBS.length + extraFbs.length);
+ System.arraycopy(extraFbs, 0, fbs, ENERGY_FBS.length, extraFbs.length);
+ return token(subscriptionId, scope, fbs);
+ }
+
+ /** A customer access token for the subscription with exactly these FB authorities. */
+ private static RequestPostProcessor token(UUID subscriptionId, String scope, String... fbs) {
+ return opaqueToken()
+ .attributes(attributes -> {
+ attributes.put("resourceURI", BASE + "/Batch/Subscription/" + subscriptionId);
+ attributes.put("scope", List.of(scope));
+ })
+ .authorities(authorities(fbs));
+ }
+
+ private static RequestPostProcessor admin() {
+ return opaqueToken().authorities(new SimpleGrantedAuthority("SCOPE_DataCustodian_Admin_Access"));
+ }
+
+ private static List authorities(String... names) {
+ return Arrays.stream(names).map(SimpleGrantedAuthority::new).toList();
+ }
+
+ private SubscriptionEntity subscription(UUID id, List usagePoints) {
+ String key = id.toString().substring(id.toString().length() - 4);
+ RetailCustomerEntity customer = new RetailCustomerEntity("batch" + key, "Sample", "Customer",
+ "batch" + key + "@example.com", RetailCustomerEntity.ROLE_USER);
+ customer.setPassword("not-used");
+ customer.setEnabled(Boolean.TRUE);
+
+ ApplicationInformationEntity application = new ApplicationInformationEntity();
+ application.setClientId("batch-client-" + key);
+ application.setDataCustodianId("data_custodian");
+ application.setGrantTypes(new HashSet<>(Set.of(GrantType.AUTHORIZATION_CODE)));
+
+ AuthorizationEntity authorization = new AuthorizationEntity();
+ authorization.setAccessToken("token-" + id);
+ authorization.setStatus(AuthorizationEntity.STATUS_ACTIVE);
+
+ SubscriptionEntity subscription = new SubscriptionEntity(id);
+ subscription.setRetailCustomer(retailCustomerRepository.save(customer));
+ subscription.setApplicationInformation(applicationInformationRepository.save(application));
+ subscription.setAuthorization(authorizationRepository.save(authorization));
+ subscription.setUsagePoints(usagePoints);
+ return subscription;
+ }
+
+ /** One UsagePoint with every child kind; one IntervalBlock from yesterday, one from 40 days ago; one
+ * UsageSummary ending now and one ElectricPowerQualitySummary ending 5 days ago, and one of each ending
+ * 60 days ago. Each collection gets its newer item first, so the feed's order comes from sorting. */
+ private static UsagePointEntity usagePointA(long now) {
+ UsagePointEntity usagePoint = new UsagePointEntity();
+ usagePoint.setId(USAGE_POINT_A);
+ usagePoint.setDescription("Sample residential electric service");
+ usagePoint.setStatus((short) 1);
+ usagePoint.setServiceCategory(ServiceCategory.ELECTRICITY);
+
+ usagePoint.setLocalTimeParameters(localTime(LOCAL_TIME_A));
+
+ ReadingTypeEntity readingType = new ReadingTypeEntity();
+ readingType.setId(READING_TYPE_A);
+ readingType.setAccumulationBehaviour("4");
+ readingType.setCommodity("1");
+ readingType.setFlowDirection("1");
+ readingType.setIntervalLength(3_600L);
+ readingType.setKind("12");
+ readingType.setPowerOfTenMultiplier("-3");
+ readingType.setUom("72");
+
+ MeterReadingEntity meterReading = new MeterReadingEntity();
+ meterReading.setId(METER_READING_A);
+ meterReading.setUsagePoint(usagePoint);
+ meterReading.setReadingType(readingType);
+ meterReading.getIntervalBlocks().add(block(RECENT_BLOCK, meterReading, now - DAY));
+ meterReading.getIntervalBlocks().add(block(OLD_BLOCK, meterReading, now - 40 * DAY));
+ usagePoint.getMeterReadings().add(meterReading);
+
+ usagePoint.getUsageSummaries().add(usageSummary(USAGE_SUMMARY_A, usagePoint, now - 30 * DAY, now));
+ usagePoint.getUsageSummaries().add(usageSummary(OLD_USAGE_SUMMARY, usagePoint, now - 90 * DAY, now));
+ usagePoint.getElectricPowerQualitySummaries().add(qualitySummary(QUALITY_SUMMARY_A, usagePoint, now - 35 * DAY));
+ usagePoint.getElectricPowerQualitySummaries().add(qualitySummary(OLD_QUALITY_SUMMARY, usagePoint, now - 90 * DAY));
+ return usagePoint;
+ }
+
+ private static UsagePointEntity usagePoint(UUID id, ServiceCategory serviceCategory) {
+ UsagePointEntity usagePoint = new UsagePointEntity();
+ usagePoint.setId(id);
+ usagePoint.setServiceCategory(serviceCategory);
+ return usagePoint;
+ }
+
+ private static TimeConfigurationEntity localTime(UUID id) {
+ TimeConfigurationEntity localTime = new TimeConfigurationEntity();
+ localTime.setId(id);
+ localTime.setTzOffset(-18_000L);
+ localTime.setDstOffset(3_600L);
+ localTime.setDstStartRule(new byte[]{0x36, 0x0E, 0x20, 0x00});
+ localTime.setDstEndRule(new byte[]{(byte) 0xB4, 0x0E, 0x20, 0x00});
+ return localTime;
+ }
+
+ /** A 30-day billing period starting at {@code start}. */
+ private static UsageSummaryEntity usageSummary(UUID id, UsagePointEntity usagePoint, long start, long now) {
+ UsageSummaryEntity summary = new UsageSummaryEntity();
+ summary.setId(id);
+ summary.setUsagePoint(usagePoint);
+ summary.setBillingPeriod(new DateTimeInterval(30 * DAY, start));
+ summary.setStatusTimeStamp(now);
+ return summary;
+ }
+
+ /** A 30-day summary interval starting at {@code start}. */
+ private static ElectricPowerQualitySummaryEntity qualitySummary(UUID id, UsagePointEntity usagePoint, long start) {
+ ElectricPowerQualitySummaryEntity quality = new ElectricPowerQualitySummaryEntity();
+ quality.setId(id);
+ quality.setUsagePoint(usagePoint);
+ quality.setSummaryInterval(new DateTimeInterval(30 * DAY, start));
+ quality.setMeasurementProtocol((short) 0);
+ quality.setMainsVoltage(240_000L);
+ quality.setFlickerPlt(0L);
+ quality.setFlickerPst(0L);
+ quality.setHarmonicVoltage(0L);
+ quality.setLongInterruptions(0L);
+ quality.setPowerFrequency(0L);
+ quality.setRapidVoltageChanges(0L);
+ quality.setShortInterruptions(0L);
+ quality.setSupplyVoltageDips(0L);
+ quality.setSupplyVoltageImbalance(0L);
+ quality.setSupplyVoltageVariations(0L);
+ quality.setTempOvervoltage(0L);
+ return quality;
+ }
+
+ private static IntervalBlockEntity block(UUID id, MeterReadingEntity meterReading, long start) {
+ IntervalBlockEntity block = new IntervalBlockEntity();
+ block.setId(id);
+ block.setMeterReading(meterReading);
+ block.setInterval(new DateTimeInterval(DAY, start));
+ IntervalReadingEntity reading = new IntervalReadingEntity();
+ reading.setIntervalBlock(block);
+ reading.setTimePeriod(new DateTimeInterval(3_600L, start));
+ reading.setValue(1_250_000L);
+ block.getIntervalReadings().add(reading);
+ return block;
+ }
+}
diff --git a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java
index 163928bd..e9e4ddf0 100644
--- a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java
+++ b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java
@@ -19,6 +19,7 @@
package org.greenbuttonalliance.espi.datacustodian.web.api.scope;
import org.greenbuttonalliance.espi.common.repositories.usage.SubscriptionRepository;
+import org.greenbuttonalliance.espi.common.scope.EspiScope;
import org.greenbuttonalliance.espi.common.uri.EspiBatchUri;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
@@ -31,6 +32,7 @@
import java.util.UUID;
import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.verifyNoInteractions;
import static org.mockito.Mockito.when;
@@ -134,4 +136,52 @@ void emptySubscriptionDenied() {
assertThat(scope.isDenied()).isTrue();
}
+
+ @Test
+ @DisplayName("canReadSubscription: the admin, or a customer token for exactly that subscription (#279)")
+ void canReadSubscription() {
+ UUID mine = UUID.fromString("11111111-2222-5333-8444-555555555555");
+ UUID other = UUID.fromString("11111111-2222-5333-8444-666666666666");
+ Authentication customer = auth(Map.of("resourceURI", EspiBatchUri.batchSubscription(BASE, mine)), "FB_4");
+ Authentication clientToken = auth(Map.of("resourceURI", EspiBatchUri.batchSubscription(BASE, mine)),
+ "ESPI_CLIENT_ACCESS_TOKEN", "FB_4");
+ Authentication bulk = auth(Map.of("resourceURI", EspiBatchUri.batchBulk(BASE, "BULK_1")), "FB_4");
+ Authentication admin = auth(Map.of("active", true), "SCOPE_DataCustodian_Admin_Access");
+
+ assertThat(List.of(resolver.canReadSubscription(customer, mine), resolver.canReadSubscription(admin, other)))
+ .containsOnly(true);
+ assertThat(List.of(
+ resolver.canReadSubscription(customer, other),
+ resolver.canReadSubscription(clientToken, mine),
+ resolver.canReadSubscription(bulk, mine),
+ resolver.canReadSubscription(null, mine),
+ resolver.canReadSubscription(customer, null)))
+ .containsOnly(false);
+ verifyNoInteractions(subscriptionRepository);
+ }
+
+ @Test
+ @DisplayName("espiScopes: every FB scope but FB=34_35 (any case); HistoryLength (seconds) is the shortest usage scope's; a bad FB scope throws")
+ void espiScopes() {
+ Authentication scopes = auth(Map.of("scope", List.of("openid", "FB=4_5_16;HistoryLength=63072000",
+ "FB=4_5;HistoryLength=31536000", "FB=51_53_54;HistoryLength=86400", "fb=34_35")));
+
+ assertThat(resolver.espiScopes(scopes))
+ .extracting(EspiScope::historyLength)
+ .containsExactly(63_072_000, 31_536_000, 86_400);
+ // The customer-data scope's HistoryLength does not limit usage data...
+ assertThat(resolver.historyLengthSeconds(scopes)).contains(31_536_000L);
+ // ...but a summary-only scope without FB_4 does.
+ assertThat(resolver.historyLengthSeconds(auth(Map.of("scope",
+ List.of("FB=4_5;HistoryLength=63072000", "FB=16_17;HistoryLength=86400"))))).contains(86_400L);
+ assertThat(resolver.historyLengthSeconds(auth(Map.of("scope", "FB=4_5 openid")))).isEmpty();
+ assertThat(List.of(
+ resolver.espiScopes(auth(Map.of("scope", List.of("FB=34_35")))),
+ resolver.espiScopes(auth(Map.of("scope", List.of("fb=34_35")))),
+ resolver.espiScopes(auth(Map.of("active", true))),
+ resolver.espiScopes(null)))
+ .allSatisfy(result -> assertThat(result).isEmpty());
+ assertThatThrownBy(() -> resolver.historyLengthSeconds(auth(Map.of("scope", List.of("FB=4_5", "FB=4_x")))))
+ .isInstanceOf(IllegalArgumentException.class);
+ }
}