001/*
002 *    GeoAPI - Java interfaces for OGC/ISO standards
003 *    Copyright © 2004-2023 Open Geospatial Consortium, Inc.
004 *    http://www.geoapi.org
005 *
006 *    Licensed under the Apache License, Version 2.0 (the "License");
007 *    you may not use this file except in compliance with the License.
008 *    You may obtain a copy of the License at
009 *
010 *        http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *    Unless required by applicable law or agreed to in writing, software
013 *    distributed under the License is distributed on an "AS IS" BASIS,
014 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 *    See the License for the specific language governing permissions and
016 *    limitations under the License.
017 */
018package org.opengis.metadata.distribution;
019
020import java.util.Date;
021import java.util.Currency;
022import java.time.temporal.Temporal;
023import org.opengis.util.Record;
024import org.opengis.util.RecordType;
025import org.opengis.util.InternationalString;
026import org.opengis.geoapi.internal.Legacy;
027import org.opengis.annotation.UML;
028
029import static org.opengis.annotation.Obligation.*;
030import static org.opengis.annotation.Specification.*;
031
032
033/**
034 * Common ways in which the resource may be obtained or received, and related instructions
035 * and fee information.
036 *
037 * @author  Martin Desruisseaux (IRD)
038 * @version 3.1
039 * @since   2.0
040 */
041@UML(identifier="MD_StandardOrderProcess", specification=ISO_19115)
042public interface StandardOrderProcess {
043    /**
044     * Fees and terms for retrieving the resource.
045     * Includes monetary units (as specified in ISO 4217).
046     * The monetary units may also be available with {@link #getCurrency()}.
047     *
048     * @return fees and terms for retrieving the resource, or {@code null}.
049     */
050    @UML(identifier="fees", obligation=OPTIONAL, specification=ISO_19115)
051    default InternationalString getFees() {
052        return null;
053    }
054
055    /**
056     * The monetary units of the {@link #getFees() fees} (as specified in ISO 4217).
057     *
058     * <p><b>Constraints:</b><br>
059     * For ISO 19115 compatibility reasons, this method is <strong>not</strong> required to return
060     * a non-null value even if the text returned by {@link #getFees()} contains a currency units.
061     * However, if this method returns a non-null value, then that value is required to be consistent
062     * with the fees text.</p>
063     *
064     * @departure integration
065     *   This method is not part of ISO specification. It has been added in GeoAPI for
066     *   integration with the standard JDK library.
067     *
068     * @return the fees monetary units, or {@code null} if none or unknown.
069     *
070     * @since 3.1
071     */
072    default Currency getCurrency() {
073        return null;
074    }
075
076    /**
077     * Date and time when the dataset will be available.
078     *
079     * @return date and time when the dataset will be available, or {@code null}.
080     *
081     * @deprecated Replaced by {@link #getPlannedAvailableDate()}.
082     */
083    @Deprecated(since="3.1")
084    default Date getPlannedAvailableDateTime() {
085        return Legacy.toDate(getPlannedAvailableDate());
086    }
087
088    /**
089     * Date and time when the dataset will be available.
090     * The returned value should be an instance of {@link java.time.LocalDate}, {@link java.time.LocalDateTime},
091     * {@link java.time.OffsetDateTime} or {@link java.time.ZonedDateTime}, depending whether hours are defined
092     * and how the timezone (if any) is defined. But other types are also allowed.
093     *
094     * @return date and time when the dataset will be available, or {@code null}.
095     *
096     * @since 3.1
097     */
098    @UML(identifier="plannedAvailableDateTime", obligation=OPTIONAL, specification=ISO_19115)
099    default Temporal getPlannedAvailableDate() {
100        return null;
101    }
102
103    /**
104     * General instructions, terms and services provided by the distributor.
105     *
106     * @return general instructions, terms and services provided by the distributor, or {@code null}.
107     */
108    @UML(identifier="orderingInstructions", obligation=OPTIONAL, specification=ISO_19115)
109    default InternationalString getOrderingInstructions() {
110        return null;
111    }
112
113    /**
114     * Typical turnaround time for the filling of an order.
115     *
116     * @return typical turnaround time for the filling of an order, or {@code null}.
117     */
118    @UML(identifier="turnaround", obligation=OPTIONAL, specification=ISO_19115)
119    default InternationalString getTurnaround() {
120        return null;
121    }
122
123    /**
124     * Description of the {@linkplain #getOrderOptions() order options} record.
125     *
126     * @return description of the order options record, or {@code null} if none.
127     *
128     * @since 3.1
129     *
130     * @see Record#getRecordType()
131     */
132    @UML(identifier="orderOptionsType", obligation=OPTIONAL, specification=ISO_19115)
133    default RecordType getOrderOptionsType() {
134        return null;
135    }
136
137    /**
138     * Request/purchase choices.
139     *
140     * @return request/purchase choices.
141     *
142     * @since 3.1
143     *
144     * @todo We presume that this record is filled by the vendor for describing the options chosen by the client
145     *       when he ordered the resource. We presume that this is not a record to be filled by the user for new
146     *       orders, otherwise this method would need to be a factory rather than a getter.
147     */
148    @UML(identifier="orderOptions", obligation=OPTIONAL, specification=ISO_19115)
149    default Record getOrderOptions() {
150        return null;
151    }
152}