001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  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,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.eclipse.aether.metadata;
020
021import java.io.File;
022import java.nio.file.Path;
023import java.util.Map;
024
025/**
026 * A piece of repository metadata, e.g. an index of available versions. In contrast to an artifact, which usually exists
027 * in only one repository, metadata usually exists in multiple repositories and each repository contains a different
028 * copy of the metadata. <em>Note:</em> Metadata instances are supposed to be immutable, e.g. any exposed mutator method
029 * returns a new metadata instance and leaves the original instance unchanged. Implementors are strongly advised to obey
030 * this contract. <em>Note:</em> Implementors are strongly advised to inherit from {@link AbstractMetadata} instead of
031 * directly implementing this interface.
032 *
033 * @noimplement This interface is not intended to be implemented by clients.
034 * @noextend This interface is not intended to be extended by clients.
035 */
036public interface Metadata {
037
038    /**
039     * The nature of the metadata.
040     */
041    enum Nature {
042        /**
043         * The metadata refers to release artifacts only.
044         */
045        RELEASE,
046
047        /**
048         * The metadata refers to snapshot artifacts only.
049         */
050        SNAPSHOT,
051
052        /**
053         * The metadata refers to either release or snapshot artifacts.
054         */
055        RELEASE_OR_SNAPSHOT
056    }
057
058    /**
059     * Gets the group identifier of this metadata.
060     *
061     * @return The group identifier or an empty string if the metadata applies to the entire repository, never
062     *         {@code null}.
063     */
064    String getGroupId();
065
066    /**
067     * Gets the artifact identifier of this metadata.
068     *
069     * @return The artifact identifier or an empty string if the metadata applies to the groupId level only, never
070     *         {@code null}.
071     */
072    String getArtifactId();
073
074    /**
075     * Gets the version of this metadata.
076     *
077     * @return The version or an empty string if the metadata applies to the groupId:artifactId level only, never
078     *         {@code null}.
079     */
080    String getVersion();
081
082    /**
083     * Gets the type of the metadata, e.g. "maven-metadata.xml".
084     *
085     * @return The type of the metadata, never {@code null}.
086     */
087    String getType();
088
089    /**
090     * Gets the nature of this metadata. The nature indicates to what artifact versions the metadata refers.
091     *
092     * @return The nature, never {@code null}.
093     */
094    Nature getNature();
095
096    /**
097     * Gets the file of this metadata. Note that only resolved metadata has a file associated with it.
098     *
099     * @return The file or {@code null} if none.
100     * @deprecated Use {@link #getPath()} instead.
101     */
102    @Deprecated
103    File getFile();
104
105    /**
106     * Gets the file of this metadata. Note that only resolved metadata has a file associated with it.
107     *
108     * @return The file or {@code null} if none.
109     * @since 2.0.0
110     */
111    Path getPath();
112
113    /**
114     * Sets the file of the metadata.
115     *
116     * @param file The file of the metadata, may be {@code null}
117     * @return The new metadata, never {@code null}.
118     * @deprecated Use {@link #setPath(Path)} instead.
119     */
120    @Deprecated
121    Metadata setFile(File file);
122
123    /**
124     * Sets the file of the metadata.
125     *
126     * @param path The file of the metadata, may be {@code null}
127     * @return The new metadata, never {@code null}.
128     * @since 2.0.0
129     */
130    Metadata setPath(Path path);
131
132    /**
133     * Gets the specified property.
134     *
135     * @param key The name of the property, must not be {@code null}.
136     * @param defaultValue The default value to return in case the property is not set, may be {@code null}.
137     * @return The requested property value or {@code null} if the property is not set and no default value was
138     *         provided.
139     */
140    String getProperty(String key, String defaultValue);
141
142    /**
143     * Gets the properties of this metadata.
144     *
145     * @return The (read-only) properties, never {@code null}.
146     */
147    Map<String, String> getProperties();
148
149    /**
150     * Sets the properties for the metadata.
151     *
152     * @param properties The properties for the metadata, may be {@code null}.
153     * @return The new metadata, never {@code null}.
154     */
155    Metadata setProperties(Map<String, String> properties);
156}