1 /*
2 * Copyright 2012-2013 smartics, Kronseder & Reiner GmbH
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package de.smartics.properties.spi.config.support;
17
18 import javax.annotation.CheckForNull;
19
20 import de.smartics.properties.api.config.app.ConfigurationPropertiesFactory;
21 import de.smartics.properties.api.config.domain.CompoundConfigurationException;
22 import de.smartics.properties.api.config.domain.ConfigurationPropertiesManagement;
23 import de.smartics.properties.api.config.domain.key.ConfigurationKey;
24 import de.smartics.properties.resource.domain.ArtifactId;
25 import de.smartics.properties.resource.domain.ArtifactRef;
26 import de.smartics.properties.resource.repository.RepositoryException;
27 import de.smartics.util.lang.NullArgumentException;
28
29 /**
30 * Factory to create instances of {@link ConfigurationPropertiesManagement}.
31 */
32 public interface ConfigurationPropertiesManagementFactory extends
33 ConfigurationPropertiesFactory
34 {
35 // ********************************* Fields *********************************
36
37 // --- constants ------------------------------------------------------------
38
39 // ****************************** Initializer *******************************
40
41 // ****************************** Inner Classes *****************************
42
43 // ********************************* Methods ********************************
44
45 // --- get&set --------------------------------------------------------------
46
47 // --- business -------------------------------------------------------------
48
49 /**
50 * Creates the configuration properties instance for the given key.
51 *
52 * @param key the key to identify the requested configuration.
53 * @return the requested configuration.
54 * @throws NullPointerException if {@code key} is <code>null</code>.
55 */
56 ConfigurationPropertiesManagement create(ConfigurationKey<?> key)
57 throws NullPointerException;
58
59 /**
60 * Removes the configuration with the given key from the cache.
61 *
62 * @param key the key of the configuration to remove.
63 * @return a reference to the removed configuration.
64 * @throws NullPointerException if {@code key} is <code>null</code>.
65 */
66 ConfigurationPropertiesManagement remove(ConfigurationKey<?> key)
67 throws NullPointerException;
68
69 /**
70 * Releases resources acquired by this instance.
71 */
72 void release();
73
74 /**
75 * Adds the URLs derived from the dependencies provided by the given
76 * {@code artifactId} to the locations to search for property
77 * {@link de.smartics.properties.api.core.domain.PropertyDescriptor
78 * declarations} and definitions. Property definitions are e.g. properties
79 * files or similar resources that define the actual value of a property.
80 * <p>
81 * Adding URLs only affects later creations of
82 * {@link de.smartics.properties.api.config.domain.ConfigurationProperties}
83 * instances.
84 * </p>
85 *
86 * @param artifactId the reference to the property resources.
87 * @return the URL to the remote repository to fetch the artifact.
88 * @throws NullArgumentException if {@code artifactId} is <code>null</code>.
89 * @throws RepositoryException on any problem accessing the remote repository.
90 * @throws CompoundConfigurationException if loading property resources
91 * encountered problems.
92 */
93 String addRootUrls(ArtifactId artifactId) throws NullArgumentException,
94 RepositoryException, CompoundConfigurationException;
95
96 /**
97 * Returns the artifact reference by its short ID.
98 *
99 * @param artifactId the GAV concatenated and separated by colons.
100 * @return the associated artifact reference or <code>null</code> if there is
101 * no artifact reference with the given {@code artifactId} registered.
102 * @throws NullPointerException if {@code artifactId} is <code>null</code>.
103 * @impl The registered artifacts are traversed in order they have been
104 * registered. The first class path environment that references the
105 * artifact with the given {@code artifactId} is returned.
106 */
107 @CheckForNull
108 ArtifactRef getArtifactRef(String artifactId) throws NullPointerException;
109
110 // --- object basics --------------------------------------------------------
111
112 }