View Javadoc
1   /*******************************************************************************
2    * Copyright (c) 2010, 2012 Sonatype, Inc.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *    Sonatype, Inc. - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.aether.metadata;
12  
13  import java.io.File;
14  import java.util.Map;
15  
16  /**
17   * A piece of repository metadata, e.g. an index of available versions. In contrast to an artifact, which usually exists
18   * in only one repository, metadata usually exists in multiple repositories and each repository contains a different
19   * copy of the metadata. <em>Note:</em> Metadata instances are supposed to be immutable, e.g. any exposed mutator method
20   * returns a new metadata instance and leaves the original instance unchanged. Implementors are strongly advised to obey
21   * this contract. <em>Note:</em> Implementors are strongly advised to inherit from {@link AbstractMetadata} instead of
22   * directly implementing this interface.
23   * 
24   * @noimplement This interface is not intended to be implemented by clients.
25   * @noextend This interface is not intended to be extended by clients.
26   */
27  public interface Metadata
28  {
29  
30      /**
31       * The nature of the metadata.
32       */
33      enum Nature
34      {
35          /**
36           * The metadata refers to release artifacts only.
37           */
38          RELEASE,
39  
40          /**
41           * The metadata refers to snapshot artifacts only.
42           */
43          SNAPSHOT,
44  
45          /**
46           * The metadata refers to either release or snapshot artifacts.
47           */
48          RELEASE_OR_SNAPSHOT
49      }
50  
51      /**
52       * Gets the group identifier of this metadata.
53       * 
54       * @return The group identifier or an empty string if the metadata applies to the entire repository, never
55       *         {@code null}.
56       */
57      String getGroupId();
58  
59      /**
60       * Gets the artifact identifier of this metadata.
61       * 
62       * @return The artifact identifier or an empty string if the metadata applies to the groupId level only, never
63       *         {@code null}.
64       */
65      String getArtifactId();
66  
67      /**
68       * Gets the version of this metadata.
69       * 
70       * @return The version or an empty string if the metadata applies to the groupId:artifactId level only, never
71       *         {@code null}.
72       */
73      String getVersion();
74  
75      /**
76       * Gets the type of the metadata, e.g. "maven-metadata.xml".
77       * 
78       * @return The type of the metadata, never {@code null}.
79       */
80      String getType();
81  
82      /**
83       * Gets the nature of this metadata. The nature indicates to what artifact versions the metadata refers.
84       * 
85       * @return The nature, never {@code null}.
86       */
87      Nature getNature();
88  
89      /**
90       * Gets the file of this metadata. Note that only resolved metadata has a file associated with it.
91       * 
92       * @return The file or {@code null} if none.
93       */
94      File getFile();
95  
96      /**
97       * Sets the file of the metadata.
98       * 
99       * @param file The file of the metadata, may be {@code null}
100      * @return The new metadata, never {@code null}.
101      */
102     Metadata setFile( File file );
103 
104     /**
105      * Gets the specified property.
106      * 
107      * @param key The name of the property, must not be {@code null}.
108      * @param defaultValue The default value to return in case the property is not set, may be {@code null}.
109      * @return The requested property value or {@code null} if the property is not set and no default value was
110      *         provided.
111      */
112     String getProperty( String key, String defaultValue );
113 
114     /**
115      * Gets the properties of this metadata.
116      * 
117      * @return The (read-only) properties, never {@code null}.
118      */
119     Map<String, String> getProperties();
120 
121     /**
122      * Sets the properties for the metadata.
123      * 
124      * @param properties The properties for the metadata, may be {@code null}.
125      * @return The new metadata, never {@code null}.
126      */
127     Metadata setProperties( Map<String, String> properties );
128 
129 }