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 }