// Copyright 2009 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.instantiator;
import com.google.common.annotations.VisibleForTesting;
import com.google.enterprise.connector.persist.ConnectorExistsException;
import com.google.enterprise.connector.persist.ConnectorNotFoundException;
import com.google.enterprise.connector.scheduler.Schedule;
import com.google.enterprise.connector.spi.AuthenticationManager;
import com.google.enterprise.connector.spi.AuthorizationManager;
import com.google.enterprise.connector.spi.ConfigureResponse;
import com.google.enterprise.connector.spi.Retriever;
import com.google.enterprise.connector.spi.TraversalManager;
import com.google.enterprise.connector.traversal.Traverser;
import com.google.enterprise.connector.util.filter.DocumentFilterFactory;
import java.util.Locale;
/**
* Management interface for a connector instance.
* <p>
* This interface provides a single point of control to allow for proper
* synchronization between concurrent
* <OL>
* <LI>Configuration operations
* <LI>Running of traversals
* </OL>
* <p>
* Note that a {@link ConnectorCoordinator} may be created with a name but not a
* complete full configuration for purposes of providing synchronization during
* the creation process. The configuration can be specified using
* {@link #setConnectorConfiguration(TypeInfo, Configuration, Locale, boolean)}
* The {@link #exists()} method will return false for a
* {@link ConnectorCoordinator} without a complete configuration. In addition
* many of the methods in this interface will throw a
* {@link ConnectorNotFoundException} if the {@link ConnectorCoordinator} does
* not have a complete configuration.
* <p>
* It is expected the caller will guarantee that each
* {@link ConnectorCoordinator} in the system has a unique name.
*/
@VisibleForTesting
public interface ConnectorCoordinator {
/**
* Returns true if this {@link ConnectorCoordinator} holds a
* configured usable connector instance. This function is for reporting
* purposes only. Concurrent operations by other threads can invalidate
* the result of calling this quickly so in code such as
* <pre>
* if (c.exists()) {
* doSomething();
* }
* </pre>
* The {@link ConnectorCoordinator} may not exist when <code>doSomething()
* </code> actually runs.
*/
public boolean exists();
/**
* Returns the name for this {@link ConnectorCoordinator}.
*/
public String getConnectorName();
/**
* Removes this {@link ConnectorCoordinator} from the system. After this
* returns {@link ConnectorCoordinator#exists()} will return false until
* someone re-creates the connector configuration by calling
* {@link #setConnectorConfiguration(TypeInfo, Configuration, Locale, boolean)}.
* This is a noop if this {@link ConnectorCoordinator} does not exist.
*/
public void removeConnector();
/**
* Returns the {@link AuthenticationManager} for this
* {@link ConnectorCoordinator}
*
* @throws ConnectorNotFoundException if this {@link ConnectorCoordinator}
* does not exist.
* @throws InstantiatorException if unable to instantiate the requested
* {@link AuthenticationManager}
*/
public AuthenticationManager getAuthenticationManager()
throws ConnectorNotFoundException, InstantiatorException;
/**
* Returns the {@link AuthorizationManager} for this
* {@link ConnectorCoordinator}
*
* @throws ConnectorNotFoundException if this {@link ConnectorCoordinator}
* does not exist.
* @throws InstantiatorException if unable to instantiate the requested
* {@link AuthorizationManager}
*/
public AuthorizationManager getAuthorizationManager()
throws ConnectorNotFoundException, InstantiatorException;
/**
* Returns the {@link TraversalManager} for this
* {@link ConnectorCoordinator}
*
* @throws ConnectorNotFoundException if this {@link ConnectorCoordinator}
* does not exist.
* @throws InstantiatorException if unable to instantiate the requested
* {@link Traverser}
*/
@VisibleForTesting
public TraversalManager getTraversalManager()
throws ConnectorNotFoundException, InstantiatorException;
/**
* Return a {@link Retriever} that may be used to access content for the
* document identified by {@code docid}. If the connector does not support
* the {@link Retriever} interface, {@code null} is returned.
*
* @return a {@link Retriever}, or {@code null} if none is available
* @throws ConnectorNotFoundException if this {@link ConnectorCoordinator}
* does not exist.
* @throws InstantiatorException if unable to instantiate the requested
* {@link Retriever}
*/
public Retriever getRetriever()
throws ConnectorNotFoundException, InstantiatorException;
/**
* Returns {@link ConfigureResponse} with a configuration form or a
* message indicating the problem.
*
* @throws ConnectorNotFoundException if this {@link ConnectorCoordinator}
* does not exist.
* @throws InstantiatorException if unable to instantiate the support
* classes needed to construct the {@link ConfigureResponse}
*/
public ConfigureResponse getConfigForm(Locale locale)
throws ConnectorNotFoundException, InstantiatorException;
/**
* Restarts the traversal for this {@link ConnectorCoordinator} by
* <OL>
* <LI> Canceling the current traversal,
* <LI> Clearing the current checkpoint.
* <LI> Starting the traversal again.
* </OL>
*
* @throws ConnectorNotFoundException if this {@link ConnectorCoordinator}
* does not exist.
*/
public void restartConnectorTraversal() throws ConnectorNotFoundException;
/**
* Sets the {@link Schedule} for this {@link ConnectorCoordinator}. If this
* {@link ConnectorCoordinator} supports persistence this will persist the
* new Schedule.
*
* @throws ConnectorNotFoundException if this {@link ConnectorCoordinator}
* does not exist.
*/
public void setConnectorSchedule(Schedule connectorSchedule)
throws ConnectorNotFoundException;
/**
* Returns the {@link Schedule} for this {@link ConnectorCoordinator}.
*
* @throws ConnectorNotFoundException if this {@link ConnectorCoordinator}
* does not exist.
*/
public Schedule getConnectorSchedule() throws ConnectorNotFoundException;
/**
* Set the Connector's traversal state.
*
* @param state a String representation of the state to store.
* If null, any previous stored state is discarded.
* @throws ConnectorNotFoundException if this {@link ConnectorCoordinator}
* does not exist.
*/
public void setConnectorState(String state)
throws ConnectorNotFoundException;
/**
* Returns the Connector's traversal state.
*
* @return String representation of the stored state, or
* null if no state is stored.
* @throws ConnectorNotFoundException if this {@link ConnectorCoordinator}
* does not exist.
*/
public String getConnectorState() throws ConnectorNotFoundException;
/**
* Returns the type name for this {@link ConnectorCoordinator}.
*
* @throws ConnectorNotFoundException if this {@link ConnectorCoordinator}
* does not exist.
*/
public String getConnectorTypeName() throws ConnectorNotFoundException;
/**
* Sets the configuration for this {@link ConnectorCoordinator}. If this
* {@link ConnectorCoordinator} supports persistence this will persist the new
* configuration.
* <p>
* Upon success this function returns
* <OL>
* <LI>null
* <LI> {@link ConfigureResponse} with a null message
* <LI> {@link ConfigureResponse} with a zero length message
* </OL>
* <p>
* Upon success if this modifies the configuration parameters then calling
* {@link ConfigureResponse#getConfigData()} on the returned value returns the
* updated configuration parameters.
*
* @param newTypeInfo the new {@link TypeInfo} for this
* {@link ConnectorCoordinator}.
* @param configuration the replacement {@link Configuration} properties for
* this {@link ConnectorCoordinator}.
* @param locale the locale for use in constructing the returned
* {@link ConfigureResponse}.
* @param update true means to update and existing configuration and flase
* means to create a new one.
*
* @throws ConnectorNotFoundException if {@link #exists()} returns false and
* update is true.
* @throws ConnectorExistsException {@link #exists()} returns true and update
* is false.
*/
public ConfigureResponse setConnectorConfiguration(TypeInfo newTypeInfo,
Configuration configuration, Locale locale, boolean update)
throws ConnectorNotFoundException, ConnectorExistsException,
InstantiatorException;
/**
* Returns the {@link Configuration} for this {@link ConnectorCoordinator}.
*
* @throws ConnectorNotFoundException if this {@link ConnectorCoordinator}
* does not exist.
*/
public Configuration getConnectorConfiguration()
throws ConnectorNotFoundException;
/**
* Sets {@code GData} configuration for GData aware Connectors.
*/
public void setGDataConfig()
throws ConnectorNotFoundException, InstantiatorException;
/**
* Returns a connector's {@link DocumentFilterFactory}. Connectors may define
* a document filter specific to that connector instance. This filter will
* be used in conjuction with the Connector Manager's document filter, and
* will act as the source for the Connector Manager's document filter.
*
* @return {@link DocumentFilterFactory} for the connector, or {@code null}
* if the connector does not define a DocumentFilterFactory.
*/
public DocumentFilterFactory getDocumentFilterFactory()
throws ConnectorNotFoundException;
/**
* Starts running a batch for this {@link ConnectorCoordinator} if a batch is
* not already running.
*
* @return true if this call started a batch
* @throws ConnectorNotFoundException if this {@link ConnectorCoordinator}
* does not exist.
*/
public boolean startBatch() throws ConnectorNotFoundException;
/**
* Shuts down this {@link ConnectorCoordinator} if {@link #exists()}.
*/
public void shutdown();
}