1 /**
2 *
3 * Copyright 2005 The Apache Software Foundation
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.geronimo.system.plugin;
18
19 import java.io.IOException;
20 import java.io.File;
21 import java.net.URL;
22 import java.util.Map;
23 import javax.security.auth.login.FailedLoginException;
24 import org.apache.geronimo.kernel.repository.Artifact;
25
26 /**
27 * Knows how to import and export configurations
28 *
29 * @version $Rev: 410741 $ $Date: 2006-05-31 21:35:48 -0700 (Wed, 31 May 2006) $
30 */
31 public interface PluginInstaller {
32 /**
33 * Lists the plugins available for download in a particular Geronimo repository.
34 *
35 * @param mavenRepository The base URL to the maven repository. This must
36 * contain the file geronimo-plugins.xml
37 * @param username Optional username, if the maven repo uses HTTP Basic authentication.
38 * Set this to null if no authentication is required.
39 * @param password Optional password, if the maven repo uses HTTP Basic authentication.
40 * Set this to null if no authentication is required.
41 */
42 public PluginList listPlugins(URL mavenRepository, String username, String password) throws IOException, FailedLoginException;
43
44 /**
45 * Lists the plugins installed in the local Geronimo server, by name and
46 * ID.
47 *
48 * @return A Map with key type String (plugin name) and value type Artifact
49 * (config ID of the plugin).
50 */
51 public Map getInstalledPlugins();
52
53 /**
54 * Gets a CofigurationMetadata for a configuration installed in the local
55 * server. Should load a saved one if available, or else create a new
56 * default one to the best of its abilities.
57 *
58 * @param moduleId Identifies the configuration. This must match a
59 * configuration currently installed in the local server.
60 * The configId must be fully resolved (isResolved() == true)
61 */
62 public PluginMetadata getPluginMetadata(Artifact moduleId);
63
64 /**
65 * Saves a ConfigurationMetadata for a particular plugin, if the server is
66 * able to record it. This can be used if you later re-export the plugin,
67 * or just want to review the information for a particular installed
68 * plugin.
69 *
70 * @param metadata The data to save. The contained configId (which must
71 * be fully resolved) identifies the configuration to save
72 * this for.
73 */
74 public void updatePluginMetadata(PluginMetadata metadata);
75
76 /**
77 * Installs a configuration from a remote repository into the local Geronimo server,
78 * including all its dependencies. The caller will get the results when the
79 * operation completes. Note that this method does not throw exceptions on failure,
80 * but instead sets the failure property of the DownloadResults.
81 *
82 * @param username Optional username, if the maven repo uses HTTP Basic authentication.
83 * Set this to null if no authentication is required.
84 * @param password Optional password, if the maven repo uses HTTP Basic authentication.
85 * Set this to null if no authentication is required.
86 * @param pluginsToInstall The list of configurations to install
87 */
88 public DownloadResults install(PluginList pluginsToInstall, String username, String password);
89
90 /**
91 * Installs a configuration from a remote repository into the local Geronimo server,
92 * including all its dependencies. The method blocks until the operation completes,
93 * but the caller will be notified of progress frequently along the way (using the
94 * supplied DownloadPoller). Therefore the caller is meant to create the poller and
95 * then call this method in a background thread. Note that this method does not
96 * throw exceptions on failure, but instead sets the failure property of the
97 * DownloadPoller.
98 *
99 * @param pluginsToInstall The list of configurations to install
100 * @param username Optional username, if the maven repo uses HTTP Basic authentication.
101 * Set this to null if no authentication is required.
102 * @param password Optional password, if the maven repo uses HTTP Basic authentication.
103 * Set this to null if no authentication is required.
104 * @param poller Will be notified with status updates as the download proceeds
105 */
106 public void install(PluginList pluginsToInstall, String username, String password, DownloadPoller poller);
107
108 /**
109 * Installs a configuration from a remote repository into the local Geronimo server,
110 * including all its dependencies. The method returns immediately, providing a key
111 * that can be used to poll the status of the download operation. Note that the
112 * installation does not throw exceptions on failure, but instead sets the failure
113 * property of the DownloadResults that the caller can poll for.
114 *
115 * @param pluginsToInstall The list of configurations to install
116 * @param username Optional username, if the maven repo uses HTTP Basic authentication.
117 * Set this to null if no authentication is required.
118 * @param password Optional password, if the maven repo uses HTTP Basic authentication.
119 * Set this to null if no authentication is required.
120 *
121 * @return A key that can be passed to checkOnInstall
122 */
123 public Object startInstall(PluginList pluginsToInstall, String username, String password);
124
125 /**
126 * Installs a configuration downloaded from a remote repository into the local Geronimo
127 * server, including all its dependencies. The method returns immediately, providing a
128 * key that can be used to poll the status of the download operation. Note that the
129 * installation does not throw exceptions on failure, but instead sets the failure
130 * property of the DownloadResults that the caller can poll for.
131 *
132 * @param carFile A CAR file downloaded from a remote repository. This is a packaged
133 * configuration with included configuration information, but it may
134 * still have external dependencies that need to be downloaded
135 * separately. The metadata in the CAR file includes a repository URL
136 * for these downloads, and the username and password arguments are
137 * used in conjunction with that.
138 * @param username Optional username, if the maven repo uses HTTP Basic authentication.
139 * Set this to null if no authentication is required.
140 * @param password Optional password, if the maven repo uses HTTP Basic authentication.
141 * Set this to null if no authentication is required.
142 *
143 * @return A key that can be passed to checkOnInstall
144 */
145 public Object startInstall(File carFile, String username, String password);
146
147 /**
148 * Gets the current progress of a download operation. Note that once the
149 * DownloadResults is returned for this operation shows isFinished = true,
150 * the operation will be forgotten, so the caller should be careful not to
151 * call this again after the download has finished.
152 *
153 * @param key Identifies the operation to check on
154 */
155 public DownloadResults checkOnInstall(Object key);
156 }