View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.eclipse.aether.metadata;
20  
21  import java.io.File;
22  import java.nio.file.Path;
23  import java.util.Map;
24  
25  /**
26   * A piece of repository metadata, e.g. an index of available versions. In contrast to an artifact, which usually exists
27   * in only one repository, metadata usually exists in multiple repositories and each repository contains a different
28   * copy of the metadata. <em>Note:</em> Metadata instances are supposed to be immutable, e.g. any exposed mutator method
29   * returns a new metadata instance and leaves the original instance unchanged. Implementors are strongly advised to obey
30   * this contract. <em>Note:</em> Implementors are strongly advised to inherit from {@link AbstractMetadata} instead of
31   * directly implementing this interface.
32   *
33   * @noimplement This interface is not intended to be implemented by clients.
34   * @noextend This interface is not intended to be extended by clients.
35   */
36  public interface Metadata {
37  
38      /**
39       * The nature of the metadata.
40       */
41      enum Nature {
42          /**
43           * The metadata refers to release artifacts only.
44           */
45          RELEASE,
46  
47          /**
48           * The metadata refers to snapshot artifacts only.
49           */
50          SNAPSHOT,
51  
52          /**
53           * The metadata refers to either release or snapshot artifacts.
54           */
55          RELEASE_OR_SNAPSHOT
56      }
57  
58      /**
59       * Gets the group identifier of this metadata.
60       *
61       * @return The group identifier or an empty string if the metadata applies to the entire repository, never
62       *         {@code null}.
63       */
64      String getGroupId();
65  
66      /**
67       * Gets the artifact identifier of this metadata.
68       *
69       * @return The artifact identifier or an empty string if the metadata applies to the groupId level only, never
70       *         {@code null}.
71       */
72      String getArtifactId();
73  
74      /**
75       * Gets the version of this metadata.
76       *
77       * @return The version or an empty string if the metadata applies to the groupId:artifactId level only, never
78       *         {@code null}.
79       */
80      String getVersion();
81  
82      /**
83       * Gets the type of the metadata, e.g. "maven-metadata.xml".
84       *
85       * @return The type of the metadata, never {@code null}.
86       */
87      String getType();
88  
89      /**
90       * Gets the nature of this metadata. The nature indicates to what artifact versions the metadata refers.
91       *
92       * @return The nature, never {@code null}.
93       */
94      Nature getNature();
95  
96      /**
97       * Gets the file of this metadata. Note that only resolved metadata has a file associated with it.
98       *
99       * @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 }