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
026 /**
027 * Knows how to import and export configurations
028 *
029 * @version $Rev: 476049 $ $Date: 2006-11-16 23:35:17 -0500 (Thu, 16 Nov 2006) $
030 */
031 public interface PluginInstaller {
032 /**
033 * Lists the plugins available for download in a particular Geronimo repository.
034 *
035 * @param mavenRepository The base URL to the maven repository. This must
036 * contain the file geronimo-plugins.xml
037 * @param username Optional username, if the maven repo uses HTTP Basic authentication.
038 * Set this to null if no authentication is required.
039 * @param password Optional password, if the maven repo uses HTTP Basic authentication.
040 * Set this to null if no authentication is required.
041 */
042 public PluginList listPlugins(URL mavenRepository, String username, String password) throws IOException, FailedLoginException;
043
044 /**
045 * Lists the plugins installed in the local Geronimo server, by name and
046 * ID.
047 *
048 * @return A Map with key type String (plugin name) and value type Artifact
049 * (config ID of the plugin).
050 */
051 public Map getInstalledPlugins();
052
053 /**
054 * Gets a CofigurationMetadata for a configuration installed in the local
055 * server. Should load a saved one if available, or else create a new
056 * default one to the best of its abilities.
057 *
058 * @param moduleId Identifies the configuration. This must match a
059 * configuration currently installed in the local server.
060 * The configId must be fully resolved (isResolved() == true)
061 */
062 public PluginMetadata getPluginMetadata(Artifact moduleId);
063
064 /**
065 * Saves a ConfigurationMetadata for a particular plugin, if the server is
066 * able to record it. This can be used if you later re-export the plugin,
067 * or just want to review the information for a particular installed
068 * plugin.
069 *
070 * @param metadata The data to save. The contained configId (which must
071 * be fully resolved) identifies the configuration to save
072 * this for.
073 */
074 public void updatePluginMetadata(PluginMetadata metadata);
075
076 /**
077 * Installs a configuration from a remote repository into the local Geronimo server,
078 * including all its dependencies. The caller will get the results when the
079 * operation completes. Note that this method does not throw exceptions on failure,
080 * but instead sets the failure property of the DownloadResults.
081 *
082 * @param username Optional username, if the maven repo uses HTTP Basic authentication.
083 * Set this to null if no authentication is required.
084 * @param password Optional password, if the maven repo uses HTTP Basic authentication.
085 * Set this to null if no authentication is required.
086 * @param pluginsToInstall The list of configurations to install
087 */
088 public DownloadResults install(PluginList pluginsToInstall, String username, String password);
089
090 /**
091 * Installs a configuration from a remote repository into the local Geronimo server,
092 * including all its dependencies. The method blocks until the operation completes,
093 * but the caller will be notified of progress frequently along the way (using the
094 * supplied DownloadPoller). Therefore the caller is meant to create the poller and
095 * then call this method in a background thread. Note that this method does not
096 * throw exceptions on failure, but instead sets the failure property of the
097 * DownloadPoller.
098 *
099 * @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 }