/* $Id$ */
/**
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You 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 org.apache.manifoldcf.crawler.interfaces;
import org.apache.manifoldcf.core.interfaces.*;
import org.apache.manifoldcf.agents.interfaces.*;
import java.io.*;
import java.util.*;
/** This interface describes an instance of a connection between a notification engine
* and ManifoldCF's standard "pull" ingestion agent.
*
* Each instance of this interface is used in only one thread at a time. Connection Pooling
* on these kinds of objects is performed by the factory which instantiates repository connectors
* from symbolic names and config parameters, and is pooled by these parameters. That is, a pooled connector
* handle is used only if all the connection parameters for the handle match.
*
* Implementers of this interface should provide a default constructor which has this signature:
*
* xxx();
*
* Connectors are either configured or not. If configured, they will persist in a pool, and be
* reused multiple times. Certain methods of a connector may be called before the connector is
* configured. This includes basically all methods that permit inspection of the connector's
* capabilities.
*
* The purpose of the notification connector is to notify people of job interruptions.
*
*/
public interface INotificationConnector extends IConnector
{
public static final String _rcsid = "@(#)$Id$";
/** Request arbitrary connector information.
* This method is called directly from the API in order to allow API users to perform any one of several
* connector-specific queries. These are usually used to create external UI's. The connector will be
* connected before this method is called.
*@param output is the response object, to be filled in by this method.
*@param command is the command, which is taken directly from the API request.
*@return true if the resource is found, false if not. In either case, output may be filled in.
*/
public boolean requestInfo(Configuration output, String command)
throws ManifoldCFException;
/** Notify of job stop due to error abort.
*@param spec is the notification specification.
*/
public void notifyOfJobStopErrorAbort(Specification spec)
throws ManifoldCFException, ServiceInterruption;
/** Notify of job stop due to manual abort.
*@param spec is the notification specification.
*/
public void notifyOfJobStopManualAbort(Specification spec)
throws ManifoldCFException, ServiceInterruption;
/** Notify of job stop due to manual pause.
*@param spec is the notification specification.
*/
public void notifyOfJobStopManualPause(Specification spec)
throws ManifoldCFException, ServiceInterruption;
/** Notify of job stop due to schedule pause.
*@param spec is the notification specification.
*/
public void notifyOfJobStopSchedulePause(Specification spec)
throws ManifoldCFException, ServiceInterruption;
/** Notify of job stop due to restart.
*@param spec is the notification specification.
*/
public void notifyOfJobStopRestart(Specification spec)
throws ManifoldCFException, ServiceInterruption;
/** Notify of job end
*@param spec is the notification specification.
*/
public void notifyOfJobEnd(Specification spec)
throws ManifoldCFException, ServiceInterruption;
// UI support methods.
//
// The UI support methods come in two varieties. The first group (inherited from IConnector) is involved
// in setting up connection configuration information.
//
// The second group is listed here. These methods are is involved in presenting and editing document specification
// information for a job.
//
// The two kinds of methods are accordingly treated differently, in that the first group cannot assume that
// the current connector object is connected, while the second group can. That is why the first group
// receives a thread context argument for all UI methods, while the second group does not need one
// (since it has already been applied via the connect() method).
/** Obtain the name of the form check javascript method to call.
*@param connectionSequenceNumber is the unique number of this connection within the job.
*@return the name of the form check javascript method.
*/
public String getFormCheckJavascriptMethodName(int connectionSequenceNumber);
/** Obtain the name of the form presave check javascript method to call.
*@param connectionSequenceNumber is the unique number of this connection within the job.
*@return the name of the form presave check javascript method.
*/
public String getFormPresaveCheckJavascriptMethodName(int connectionSequenceNumber);
/** Output the specification header section.
* This method is called in the head section of a job page which has selected a repository connection of the
* current type. Its purpose is to add the required tabs to the list, and to output any javascript methods
* that might be needed by the job editing HTML.
* The connector will be connected before this method can be called.
*@param out is the output to which any HTML should be sent.
*@param locale is the locale the output is preferred to be in.
*@param ds is the current document specification for this job.
*@param connectionSequenceNumber is the unique number of this connection within the job.
*@param tabsArray is an array of tab names. Add to this array any tab names that are specific to the connector.
*/
public void outputSpecificationHeader(IHTTPOutput out, Locale locale, Specification ds,
int connectionSequenceNumber, List<String> tabsArray)
throws ManifoldCFException, IOException;
/** Output the specification body section.
* This method is called in the body section of a job page which has selected a repository connection of the
* current type. Its purpose is to present the required form elements for editing.
* The coder can presume that the HTML that is output from this configuration will be within appropriate
* <html>, <body>, and <form> tags. The name of the form is always "editjob".
* The connector will be connected before this method can be called.
*@param out is the output to which any HTML should be sent.
*@param locale is the locale the output is preferred to be in.
*@param ds is the current document specification for this job.
*@param connectionSequenceNumber is the unique number of this connection within the job.
*@param actualSequenceNumber is the connection within the job that has currently been selected.
*@param tabName is the current tab name. (actualSequenceNumber, tabName) form a unique tuple within
* the job.
*/
public void outputSpecificationBody(IHTTPOutput out, Locale locale, Specification ds,
int connectionSequenceNumber, int actualSequenceNumber, String tabName)
throws ManifoldCFException, IOException;
/** Process a specification post.
* This method is called at the start of job's edit or view page, whenever there is a possibility that form
* data for a connection has been posted. Its purpose is to gather form information and modify the
* document specification accordingly. The name of the posted form is always "editjob".
* The connector will be connected before this method can be called.
*@param variableContext contains the post data, including binary file-upload information.
*@param locale is the locale the output is preferred to be in.
*@param ds is the current document specification for this job.
*@param connectionSequenceNumber is the unique number of this connection within the job.
*@return null if all is well, or a string error message if there is an error that should prevent saving of
* the job (and cause a redirection to an error page).
*/
public String processSpecificationPost(IPostParameters variableContext, Locale locale, Specification ds,
int connectionSequenceNumber)
throws ManifoldCFException;
/** View specification.
* This method is called in the body section of a job's view page. Its purpose is to present the document
* specification information to the user. The coder can presume that the HTML that is output from
* this configuration will be within appropriate <html> and <body> tags.
* The connector will be connected before this method can be called.
*@param out is the output to which any HTML should be sent.
*@param locale is the locale the output is preferred to be in.
*@param ds is the current document specification for this job.
*@param connectionSequenceNumber is the unique number of this connection within the job.
*/
public void viewSpecification(IHTTPOutput out, Locale locale, Specification ds,
int connectionSequenceNumber)
throws ManifoldCFException, IOException;
}