001/*
002 * JDrupes Builder
003 * Copyright (C) 2025 Michael N. Lipp
004 * 
005 * This program is free software: you can redistribute it and/or modify
006 * it under the terms of the GNU Affero General Public License as
007 * published by the Free Software Foundation, either version 3 of the
008 * License, or (at your option) any later version.
009 *
010 * This program is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
013 * GNU Affero General Public License for more details.
014 *
015 * You should have received a copy of the GNU Affero General Public License
016 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
017 */
018
019package org.jdrupes.builder.api;
020
021import java.time.Instant;
022import java.util.Optional;
023import java.util.SequencedSet;
024import java.util.stream.Stream;
025
026/// Defines a container for a collection of resources. Implementations
027/// must behave as sets (no duplicate entries) and must maintain insertion
028/// order when providing the content through [stream].
029///
030/// @param <T> the contained type
031///
032public interface Resources<T extends Resource> extends Resource {
033
034    /// Adds the given resource.
035    ///
036    /// @param resource the resource
037    /// @return the resources
038    ///
039    Resources<T> add(T resource);
040
041    /// Adds all resources from the given collection.
042    ///
043    /// @param resources the resources to add
044    /// @return the resources
045    ///
046    default Resources<T> addAll(Resources<? extends T> resources) {
047        return addAll(resources.stream());
048    }
049
050    /// Adds all resources from the given stream. This consumes the given
051    /// stream.
052    ///
053    /// @param resources the resources to add
054    /// @return the resources
055    ///
056    default Resources<T> addAll(Stream<? extends T> resources) {
057        resources.forEach(this::add);
058        return this;
059    }
060
061    @Override
062    default Optional<Instant> asOf() {
063        return stream()
064            .reduce((newest, next) -> next.isNewerThan(newest) ? next : newest)
065            .map(Resource::asOf).orElse(Optional.empty());
066    }
067
068    /// Checks if is empty. The default implementation returns
069    /// `get().isEmpty()`. Implementing classes should provide a more
070    /// efficient implementation.
071    ///
072    /// @return true, if is empty
073    ///
074    default boolean isEmpty() {
075        return get().isEmpty();
076    }
077
078    /// Returns the resources as a [SequencedSet]. 
079    ///
080    /// @return the sequenced set
081    ///
082    SequencedSet<T> get();
083
084    /// Retrieves the resources as a stream.
085    ///
086    /// @return the stream
087    ///
088    default Stream<T> stream() {
089        return get().stream();
090    }
091
092    /// Clears the contained resources.
093    ///
094    /// @return the resources
095    ///
096    Resources<T> clear();
097
098    /// Creates a new resource container with elements of the given type.
099    ///
100    /// @param <T> the generic type
101    /// @param type the type
102    /// @return the resources container
103    ///
104    @SuppressWarnings("unchecked")
105    static <T extends Resource> Resources<T> with(Class<T> type) {
106        return (Resources<T>) of(ResourceType.create(Resources.class, type));
107    }
108
109    /// Creates a new resource container with elements of the given type.
110    ///
111    /// @param <T> the generic type
112    /// @param type the type
113    /// @return the resources container
114    ///
115    static <T extends Resource> Resources<T> with(ResourceType<T> type) {
116        return of(ResourceType.resourceType(Resources.class, type));
117    }
118
119    /// Creates a new resource container with the specified type.
120    ///
121    /// @param <T> the generic type
122    /// @param type the type
123    /// @return the resources container
124    ///
125    @SuppressWarnings("PMD.ShortMethodName")
126    static <T extends Resource> T of(ResourceType<T> type) {
127        return ResourceFactory.create(type);
128    }
129}