001 /**
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.geronimo.system.plugin;
018
019 import java.io.IOException;
020 import java.io.File;
021 import java.net.URL;
022 import java.util.Map;
023 import javax.security.auth.login.FailedLoginException;
024 import org.apache.geronimo.kernel.repository.Artifact;
025 import org.apache.geronimo.kernel.repository.Dependency;
026 import org.apache.geronimo.kernel.repository.MissingDependencyException;
027 import org.apache.geronimo.kernel.config.ConfigurationManager;
028 import org.apache.geronimo.kernel.config.NoSuchStoreException;
029 import org.apache.geronimo.kernel.InvalidGBeanException;
030 import org.apache.geronimo.system.plugin.model.PluginListType;
031 import org.apache.geronimo.system.plugin.model.PluginType;
032 import org.apache.geronimo.system.plugin.model.AttributesType;
033
034 /**
035 * Knows how to import and export configurations
036 *
037 * @version $Rev: 706640 $ $Date: 2008-10-21 14:44:05 +0000 (Tue, 21 Oct 2008) $
038 */
039 public interface PluginInstaller {
040 /**
041 * Lists the plugins available for download in a particular Geronimo repository.
042 *
043 * @param mavenRepository The base URL to the maven repository. This must
044 * contain the file geronimo-plugins.xml
045 * @param username Optional username, if the maven repo uses HTTP Basic authentication.
046 * Set this to null if no authentication is required.
047 * @param password Optional password, if the maven repo uses HTTP Basic authentication.
048 * Set this to null if no authentication is required.
049 */
050 public PluginListType listPlugins(URL mavenRepository, String username, String password) throws IOException, FailedLoginException;
051
052 /**
053 * Lists the plugins installed in the local Geronimo server, by name and
054 * ID.
055 *
056 * @return A Map with key type String (plugin name) and value type Artifact
057 * (config ID of the plugin).
058 */
059 public Map getInstalledPlugins();
060
061 /**
062 * Gets a CofigurationMetadata for a configuration installed in the local
063 * server. Should load a saved one if available, or else create a new
064 * default one to the best of its abilities.
065 *
066 * @param moduleId Identifies the configuration. This must match a
067 * configuration currently installed in the local server.
068 * The configId must be fully resolved (isResolved() == true)
069 */
070 public PluginType getPluginMetadata(Artifact moduleId);
071
072 /**
073 * Saves a ConfigurationMetadata for a particular plugin, if the server is
074 * able to record it. This can be used if you later re-export the plugin,
075 * or just want to review the information for a particular installed
076 * plugin.
077 *
078 * @param metadata The data to save. The contained configId (which must
079 * be fully resolved) identifies the configuration to save
080 * this for.
081 */
082 public void updatePluginMetadata(PluginType metadata);
083
084 /**
085 * Installs a configuration from a remote repository into the local Geronimo server,
086 * including all its dependencies. The caller will get the results when the
087 * operation completes. Note that this method does not throw exceptions on failure,
088 * but instead sets the failure property of the DownloadResults.
089 *
090 * @param pluginsToInstall The list of configurations to install
091 * @param defaultRepository
092 * @param restrictToDefaultRepository
093 * @param username Optional username, if the maven repo uses HTTP Basic authentication.
094 * Set this to null if no authentication is required.
095 * @param password Optional password, if the maven repo uses HTTP Basic authentication.
096 * Set this to null if no authentication is required.
097 */
098 public DownloadResults install(PluginListType pluginsToInstall, String defaultRepository, boolean restrictToDefaultRepository, String username, String password);
099
100 /**
101 * Installs a configuration from a remote repository into the local Geronimo server,
102 * including all its dependencies. The method blocks until the operation completes,
103 * but the caller will be notified of progress frequently along the way (using the
104 * supplied DownloadPoller). Therefore the caller is meant to create the poller and
105 * then call this method in a background thread. Note that this method does not
106 * throw exceptions on failure, but instead sets the failure property of the
107 * DownloadPoller.
108 *
109 * @param pluginsToInstall The list of configurations to install
110 * @param defaultRepository
111 * @param restrictToDefaultRepository
112 * @param username Optional username, if the maven repo uses HTTP Basic authentication.
113 * Set this to null if no authentication is required.
114 * @param password Optional password, if the maven repo uses HTTP Basic authentication.
115 * Set this to null if no authentication is required.
116 * @param poller Will be notified with status updates as the download proceeds
117 */
118 public void install(PluginListType pluginsToInstall, String defaultRepository, boolean restrictToDefaultRepository, String username, String password, DownloadPoller poller);
119
120 /**
121 * Installs a configuration from a remote repository into the local Geronimo server,
122 * including all its dependencies. The method returns immediately, providing a key
123 * that can be used to poll the status of the download operation. Note that the
124 * installation does not throw exceptions on failure, but instead sets the failure
125 * property of the DownloadResults that the caller can poll for.
126 *
127 * @param pluginsToInstall The list of configurations to install
128 * @param defaultRepository
129 * @param restrictToDefaultRepository
130 * @param username Optional username, if the maven repo uses HTTP Basic authentication.
131 * Set this to null if no authentication is required.
132 * @param password Optional password, if the maven repo uses HTTP Basic authentication.
133 * Set this to null if no authentication is required.
134 * @return A key that can be passed to checkOnInstall
135 */
136 public Object startInstall(PluginListType pluginsToInstall, String defaultRepository, boolean restrictToDefaultRepository, String username, String password);
137
138 /**
139 * Installs a configuration downloaded from a remote repository into the local Geronimo
140 * server, including all its dependencies. The method returns immediately, providing a
141 * key that can be used to poll the status of the download operation. Note that the
142 * installation does not throw exceptions on failure, but instead sets the failure
143 * property of the DownloadResults that the caller can poll for.
144 *
145 * @param carFile A CAR file downloaded from a remote repository. This is a packaged
146 * configuration with included configuration information, but it may
147 * still have external dependencies that need to be downloaded
148 * separately. The metadata in the CAR file includes a repository URL
149 * for these downloads, and the username and password arguments are
150 * used in conjunction with that.
151 * @param defaultRepository
152 * @param restrictToDefaultRepository
153 * @param username Optional username, if the maven repo uses HTTP Basic authentication.
154 * Set this to null if no authentication is required.
155 * @param password Optional password, if the maven repo uses HTTP Basic authentication.
156 * Set this to null if no authentication is required.
157 * @return A key that can be passed to checkOnInstall
158 */
159 public Object startInstall(File carFile, String defaultRepository, boolean restrictToDefaultRepository, String username, String password);
160
161 /**
162 * Gets the current progress of a download operation. Note that once the
163 * DownloadResults is returned for this operation shows isFinished = true,
164 * the operation will be forgotten, so the caller should be careful not to
165 * call this again after the download has finished.
166 *
167 * @param key Identifies the operation to check on
168 */
169 public DownloadResults checkOnInstall(Object key);
170
171 /**
172 * Gets the current progress of a download operation.
173 *
174 * @param key Identifies the operation to check on
175 * @param remove If true and the download operation has finished, the DownloadResults
176 * will be forgotten and the next call to this function will return null.
177 * Otherwise, the DownloadResults will be retained until this function is
178 * called with the <tt>remove</tt> parameter set to true. This parameter is
179 * only used when the download operation has finished
180 * (DownloadResults.isFinished() returns true).
181 */
182 public DownloadResults checkOnInstall(Object key, boolean remove);
183
184 /**
185 * Ensures that a plugin artifact is installable. Checks the Geronimo version,
186 * JVM version, and whether or not the plugin is already installed.
187 *
188 * @param plugin plugin artifact to check
189 * @throws org.apache.geronimo.kernel.repository.MissingDependencyException
190 * if a dependency is not satisfied
191 */
192 public void validatePlugin(PluginType plugin) throws MissingDependencyException;
193
194 /**
195 * Ensures that a plugin's prerequisites are installed
196 *
197 * @param plugin plugin artifact to check
198 * @return array of missing depedencies
199 */
200 public Dependency[] checkPrerequisites(PluginType plugin);
201
202 PluginListType createPluginListForRepositories(String repo) throws NoSuchStoreException;
203
204 public Artifact installLibrary(File libFile, String groupId) throws IOException;
205
206 DownloadResults installPluginList(String targetRepositoryPath, String relativeTargetServerPath, PluginListType pluginList) throws Exception;
207
208 void mergeOverrides(String server, AttributesType overrides) throws InvalidGBeanException, IOException;
209 }