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.util.Map;
023
024/**
025 * A piece of repository metadata, e.g. an index of available versions. In contrast to an artifact, which usually exists
026 * in only one repository, metadata usually exists in multiple repositories and each repository contains a different
027 * copy of the metadata. <em>Note:</em> Metadata instances are supposed to be immutable, e.g. any exposed mutator method
028 * returns a new metadata instance and leaves the original instance unchanged. Implementors are strongly advised to obey
029 * this contract. <em>Note:</em> Implementors are strongly advised to inherit from {@link AbstractMetadata} instead of
030 * directly implementing this interface.
031 *
032 * @noimplement This interface is not intended to be implemented by clients.
033 * @noextend This interface is not intended to be extended by clients.
034 */
035public interface Metadata {
036
037    /**
038     * The nature of the metadata.
039     */
040    enum Nature {
041        /**
042         * The metadata refers to release artifacts only.
043         */
044        RELEASE,
045
046        /**
047         * The metadata refers to snapshot artifacts only.
048         */
049        SNAPSHOT,
050
051        /**
052         * The metadata refers to either release or snapshot artifacts.
053         */
054        RELEASE_OR_SNAPSHOT
055    }
056
057    /**
058     * Gets the group identifier of this metadata.
059     *
060     * @return The group identifier or an empty string if the metadata applies to the entire repository, never
061     *         {@code null}.
062     */
063    String getGroupId();
064
065    /**
066     * Gets the artifact identifier of this metadata.
067     *
068     * @return The artifact identifier or an empty string if the metadata applies to the groupId level only, never
069     *         {@code null}.
070     */
071    String getArtifactId();
072
073    /**
074     * Gets the version of this metadata.
075     *
076     * @return The version or an empty string if the metadata applies to the groupId:artifactId level only, never
077     *         {@code null}.
078     */
079    String getVersion();
080
081    /**
082     * Gets the type of the metadata, e.g. "maven-metadata.xml".
083     *
084     * @return The type of the metadata, never {@code null}.
085     */
086    String getType();
087
088    /**
089     * Gets the nature of this metadata. The nature indicates to what artifact versions the metadata refers.
090     *
091     * @return The nature, never {@code null}.
092     */
093    Nature getNature();
094
095    /**
096     * Gets the file of this metadata. Note that only resolved metadata has a file associated with it.
097     *
098     * @return The file or {@code null} if none.
099     */
100    File getFile();
101
102    /**
103     * Sets the file of the metadata.
104     *
105     * @param file The file of the metadata, may be {@code null}
106     * @return The new metadata, never {@code null}.
107     */
108    Metadata setFile(File file);
109
110    /**
111     * Gets the specified property.
112     *
113     * @param key The name of the property, must not be {@code null}.
114     * @param defaultValue The default value to return in case the property is not set, may be {@code null}.
115     * @return The requested property value or {@code null} if the property is not set and no default value was
116     *         provided.
117     */
118    String getProperty(String key, String defaultValue);
119
120    /**
121     * Gets the properties of this metadata.
122     *
123     * @return The (read-only) properties, never {@code null}.
124     */
125    Map<String, String> getProperties();
126
127    /**
128     * Sets the properties for the metadata.
129     *
130     * @param properties The properties for the metadata, may be {@code null}.
131     * @return The new metadata, never {@code null}.
132     */
133    Metadata setProperties(Map<String, String> properties);
134}