001package org.eclipse.aether.metadata;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 * 
012 *  http://www.apache.org/licenses/LICENSE-2.0
013 * 
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import java.io.File;
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    /**
040     * The nature of the metadata.
041     */
042    enum Nature
043    {
044        /**
045         * The metadata refers to release artifacts only.
046         */
047        RELEASE,
048
049        /**
050         * The metadata refers to snapshot artifacts only.
051         */
052        SNAPSHOT,
053
054        /**
055         * The metadata refers to either release or snapshot artifacts.
056         */
057        RELEASE_OR_SNAPSHOT
058    }
059
060    /**
061     * Gets the group identifier of this metadata.
062     * 
063     * @return The group identifier or an empty string if the metadata applies to the entire repository, never
064     *         {@code null}.
065     */
066    String getGroupId();
067
068    /**
069     * Gets the artifact identifier of this metadata.
070     * 
071     * @return The artifact identifier or an empty string if the metadata applies to the groupId level only, never
072     *         {@code null}.
073     */
074    String getArtifactId();
075
076    /**
077     * Gets the version of this metadata.
078     * 
079     * @return The version or an empty string if the metadata applies to the groupId:artifactId level only, never
080     *         {@code null}.
081     */
082    String getVersion();
083
084    /**
085     * Gets the type of the metadata, e.g. "maven-metadata.xml".
086     * 
087     * @return The type of the metadata, never {@code null}.
088     */
089    String getType();
090
091    /**
092     * Gets the nature of this metadata. The nature indicates to what artifact versions the metadata refers.
093     * 
094     * @return The nature, never {@code null}.
095     */
096    Nature getNature();
097
098    /**
099     * Gets the file of this metadata. Note that only resolved metadata has a file associated with it.
100     * 
101     * @return The file or {@code null} if none.
102     */
103    File getFile();
104
105    /**
106     * Sets the file of the metadata.
107     * 
108     * @param file The file of the metadata, may be {@code null}
109     * @return The new metadata, never {@code null}.
110     */
111    Metadata setFile( File file );
112
113    /**
114     * Gets the specified property.
115     * 
116     * @param key The name of the property, must not be {@code null}.
117     * @param defaultValue The default value to return in case the property is not set, may be {@code null}.
118     * @return The requested property value or {@code null} if the property is not set and no default value was
119     *         provided.
120     */
121    String getProperty( String key, String defaultValue );
122
123    /**
124     * Gets the properties of this metadata.
125     * 
126     * @return The (read-only) properties, never {@code null}.
127     */
128    Map<String, String> getProperties();
129
130    /**
131     * Sets the properties for the metadata.
132     * 
133     * @param properties The properties for the metadata, may be {@code null}.
134     * @return The new metadata, never {@code null}.
135     */
136    Metadata setProperties( Map<String, String> properties );
137
138}