// Copyright 2006 Google Inc. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package com.google.enterprise.connector.manager; import com.google.enterprise.connector.instantiator.Configuration; import com.google.enterprise.connector.instantiator.InstantiatorException; import com.google.enterprise.connector.persist.ConnectorExistsException; import com.google.enterprise.connector.persist.ConnectorNotFoundException; import com.google.enterprise.connector.persist.ConnectorTypeNotFoundException; import com.google.enterprise.connector.persist.PersistentStoreException; import com.google.enterprise.connector.spi.AuthenticationIdentity; import com.google.enterprise.connector.spi.AuthenticationResponse; import com.google.enterprise.connector.spi.AuthorizationResponse; import com.google.enterprise.connector.spi.ConfigureResponse; import com.google.enterprise.connector.spi.ConnectorType; import com.google.enterprise.connector.spi.Document; import com.google.enterprise.connector.spi.RepositoryException; import java.io.InputStream; import java.util.Collection; import java.util.List; import java.util.Properties; import java.util.Set; /** * The main interface to the Connector Manager. Front ends such as servlets or * main() programs may be built using this. */ public interface Manager { /** * Gets the current configuration of the Connector Manager itself. * * @return the current configuration settings in a Properties object. Keys * to the Properties are the same as the keys in the property file. * @throws PersistentStoreException if there was a problem retrieving the * configuration. */ public Properties getConnectorManagerConfig() throws PersistentStoreException; /** * Stores configuration changes to the Connector Manager itself. * * @param feederGateProtocol The GSA feeder gate protocol; one of * {@code "http"}, {@code "https"}, {@code ""}, or {@code null} * @param feederGateHost The GSA host expressed as a String * @param feederGatePort The GSA feeder gate HTTP port number * @param feederGateSecurePort The GSA feeder gate HTTP port number * @param connectorManagerUrl URL string for the Connector Manager servlet * @throws PersistentStoreException If there was a problem storing the * configuration */ public void setConnectorManagerConfig(String feederGateProtocol, String feederGateHost, int feederGatePort, int feederGateSecurePort, String connectorManagerUrl) throws PersistentStoreException; /** * Returns a list of connector types that this manager knows about. * * @return A Set of Strings - the name of each connector implementation. */ public Set<String> getConnectorTypeNames(); /** * Returns the ConnectorType that is associated with the supplied name. * * @param typeName a ConnectorType name. * @return an instance of ConnectorType associated with the typeName. * @throws ConnectorTypeNotFoundException if the connector type is not found. */ public ConnectorType getConnectorType(String typeName) throws ConnectorTypeNotFoundException; /** * Returns a list of ConnectorStatus objects for each connector that this * manager knows about. * * @return A list of ConnectorStatus objects. */ public List<ConnectorStatus> getConnectorStatuses(); /** * Returns the status of a particular connector. * * @param connectorName the name of the connector instance * @throws ConnectorNotFoundException If the named connector is not known to * this manager. * @return Document containing XML configuration - DTD TBD. */ public ConnectorStatus getConnectorStatus(String connectorName) throws ConnectorNotFoundException; /** * Get initial configuration form snippet for a connector type. * * @param connectorTypeName The name of a connector implementation - it should * be one that this manager knows about (one that would be returned by * a call to getConnectorTypes()). * @param language A locale string, such as "en" or "fr_CA" which the * implementation may use to produce appropriate descriptions and * messages * @return a ConfigureResponse object, which may be null. If the return object * is null or the form is null or empty, then the caller will use a * default form. * @throws ConnectorTypeNotFoundException If the named connector type is not * known to this manager. * @throws InstantiatorException */ public ConfigureResponse getConfigForm(String connectorTypeName, String language) throws ConnectorTypeNotFoundException, InstantiatorException; /** * Get configuration data as a form snippet for an existing connnector. This * is different from getConfigForm because this is used to change the * configuration of a saved, configured Connector instance, not to configure a * new Connector instance. * * @param connectorName The connector for which to fetch configuration * @param language A locale string, such as "en" or "fr_CA" which the * implementation may use to produce appropriate descriptions and * messages * @return a ConfigureResponse object. As above, if the return object is null * or the message and form are null or empty, then the caller will use * a default form. * @throws ConnectorNotFoundException If the named connector is not known to * this manager. * @throws InstantiatorException */ public ConfigureResponse getConfigFormForConnector(String connectorName, String language) throws ConnectorNotFoundException, InstantiatorException; /** * Set config data for a new Connector or update config data for a running * Connector instance * * @param connectorName The connector to update * @param configuration A {@link Configuration} containing the connector's * connectorType-specific configuration data * @param language A locale string, such as "en" or "fr_CA" which the * implementation may use to produce appropriate descriptions and * messages * @param update A boolean true to update the giving existing connector, * false to create a new connector for the given connector name * @return a ConfigureResponse object. If the return object is null, then this * means that the configuration was valid and has been successfully * stored. If the object is non-null, then the caller should try * again. * @throws ConnectorNotFoundException If the named connector is not known to * this manager. * @throws PersistentStoreException If there was a problem storing the * configuration * @throws InstantiatorException If the instantiator cannot store the * configuration */ public ConfigureResponse setConnectorConfiguration(String connectorName, Configuration configuration, String language, boolean update) throws ConnectorNotFoundException, ConnectorExistsException, PersistentStoreException, InstantiatorException; /** * Authenticates an Identity against a named connector. * * @param connectorName * @param identity An AuthenticationIdentity object that encapsulates the * user's identity * @return an AuthenticationResponse */ public AuthenticationResponse authenticate(String connectorName, AuthenticationIdentity identity); /** * Gets authorization from a named connector for a set of documents by ID. * * @param connectorName * @param docidList The document set represented as a list of Strings: the * docid for each document * @param identity An AuthenticationIdentity object that encapsulates the * user's identity * @return A {@code Collection} of {@link AuthorizationResponse} objects. * The collection of responses need not be in the same order as the * collection of docids. The returned collection of responses may * contain only those docids for which the user has positive access, * although inclusion of items with deny access is recommended. * A return value of {@code null} indicates that the documents could * not be authorized for some reason, and no access rights (positive * or negative) should be inferred. */ public Collection<AuthorizationResponse> authorizeDocids(String connectorName, List<String> docidList, AuthenticationIdentity identity); /** * Return an {@code InputStream} that may be used to access content for the * document identified by {@code docid}. * * @param connectorName * @param docid the document identifier * @return an InputStream for the document content, or {@code null} if * document content is not available. */ public InputStream getDocumentContent(String connectorName, String docid) throws ConnectorNotFoundException, InstantiatorException, RepositoryException; /** * Return a {@link Document} that contains meta-data for the * document identified by {@code docid}, but not the actual content. * * @param connectorName * @param docid the document identifier * @return a {@link Document} containing the document meta-data, * or {@code null} if document content is not available. */ public Document getDocumentMetaData(String connectorName, String docid) throws ConnectorNotFoundException, InstantiatorException, RepositoryException; /** * Set schedule for a given Connector. * * @param connectorName * @param schedule stringified Schedule * @throws ConnectorNotFoundException If the named connector is not known to * this manager. * @throws PersistentStoreException If there was a problem storing the * configuration */ public void setSchedule(String connectorName, String schedule) throws ConnectorNotFoundException, PersistentStoreException; /** * Remove the named connector. * * @param connectorName * @throws ConnectorNotFoundException If the named connector is not known to * this manager. * @throws PersistentStoreException If there was a problem storing the * configuration */ public void removeConnector(String connectorName) throws ConnectorNotFoundException, PersistentStoreException, InstantiatorException; /** * Restart the Traverser for the named connector. * This resets the Traverser, re-indexing the repository from scratch. * * @param connectorName * @throws ConnectorNotFoundException * @throws InstantiatorException */ public void restartConnectorTraversal(String connectorName) throws ConnectorNotFoundException, InstantiatorException; /** * Get a connector's ConnectorType-specific configuration data * * @param connectorName the connector to look up * @return a {@link Configuration} of its ConnectorType-specific * configuration data * @throws ConnectorNotFoundException if the named connector is not found */ public Configuration getConnectorConfiguration(String connectorName) throws ConnectorNotFoundException; /** * @return true if the manager is currently locked, false otherwise. */ public boolean isLocked(); }