// 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.spi; import java.util.Locale; import java.util.Map; /** * The root of the SPI for connector configuration. The connector manager will * use <a href="http://www.springframework.org/">Spring</a> to instantiate * objects that implement this interface. The implementor <strong>must</strong> * provide a Spring XML configuration file named {@code connectorType.xml} to * control this process. See the package documentation for more details. * * @since 1.0 */ public interface ConnectorType { /** * Get initial configuration form snippet. * @param locale a java.util.Locale which the implementation may use to * produce appropriate descriptions and messages * * @return a ConfigureResponse object */ public ConfigureResponse getConfigForm(Locale locale); /** * Get populated configuration form snippet. Note, the values contained in the * given {@code configMap} will be raw - that is, they will not be encoded and * may contain special XML characters. It is the responsibility of the * implementation to properly replace any special characters in the * {@code configMap} values with predefined entities when they are added to * the created form snippet within the returned {@link ConfigureResponse}. * * @param configMap A map of name, value pairs (String, String) of * configuration data. Note that configuration Map key names * beginning with "google" are reserved for use by the Connector * Manager. * @param locale a java.util.Locale which the implementation may use to * produce appropriate descriptions and messages * @return a ConfigureResponse object. The form must be prepopulated with the * supplied data in the map. * @see XmlUtils#xmlAppendAttrValue(String, Appendable) */ public ConfigureResponse getPopulatedConfigForm(Map<String, String> configMap, Locale locale); /** * Validates config data and returns a new form snippet and error message if * needed. * * @param configData a {@link java.util.Map} of name, value pairs * (String, String) of configuration data. The configData map may * contain configuration data items that did not originate from the * original configForm, specifically, additional entries with names * that begin with "google". * @param locale a {@link java.util.Locale} which the implementation may use * to produce appropriate descriptions and messages * @param connectorFactory a {@link ConnectorFactory} object that can be used * by the {@link ConnectorType} to construct a {@link Connector} * instance, instantiated by the Connector Manager in exactly the * same way as it would if this config were valid and persisted. * @return a {@link ConfigureResponse} object. If the returned object is * {@code null}, this means that the configuration is acceptable. * If the returned object is non-{@code null}, then the response * contains a new form snippet (and message, as appropriate). * If the returned object is non-{@code null}, and the response * contains only a {@code Map} of configData (but no message * or form snippet), then the returned configuration is acceptable, * but may be different than the supplied configData. If a modified * configuration map is returned, it must preserve configuration * items with names beginning with "google". * @since 1.0.1 */ public ConfigureResponse validateConfig(Map<String, String> configData, Locale locale, ConnectorFactory connectorFactory); }