com.streamsets.pipeline.api.ConfigDef Maven / Gradle / Ivy
The newest version!
/*
* Copyright 2017 StreamSets 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.streamsets.pipeline.api;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.util.Collections;
import java.util.List;
import java.util.Map;
/**
* The ConfigDef annotation is used to define stage configuration variables and their visual
* representation in the UI.
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface ConfigDef {
/**
* Enum defining the possible types of the configuration variable.
*/
public enum Type {
BOOLEAN(false),
NUMBER(0),
STRING(""),
LIST(Collections.emptyList()),
MAP(Collections.emptyList()),
/**
* If a configuration variable is defined as Model, the variable must also be annotated with a model
* annotation.
*
* @see FieldSelectorModel
* @see ValueChooserModel
* @see MultiValueChooserModel
* @see PredicateModel
* @see ListBeanModel
*/
MODEL(""),
CHARACTER(' '),
TEXT(""),
CREDENTIAL(""),
/*
* Runtime type is never displayed in UI nor serialized in the pipeline configuration. Rather it's provided
* during runtime by other means.
*/
RUNTIME(null),
;
private final transient Object defaultValue;
Type(Object defaultValue) {
this.defaultValue = defaultValue;
}
/**
* Returns the default value for the configuration type to be used when there is no default value defined.
*
* @param variableClass the variable class.
*
* @return the default value for the configuration type.
*/
public Object getDefault(Class variableClass) {
Object value;
if (variableClass.isEnum()) {
value = variableClass.getEnumConstants()[0];
} else if (Map.class.isAssignableFrom(variableClass)) {
value = Collections.emptyMap();
} else if (List.class.isAssignableFrom(variableClass)) {
value = Collections.emptyList();
} else {
value = defaultValue;
}
return value;
}
}
/**
* Enum defining the possible UI syntax highlighting for a configuration of type {@link Type#TEXT}.
*
* @see #mode()
*/
public enum Mode {JAVA, JAVASCRIPT, JSON, PLAIN_TEXT, PYTHON, RUBY, SCALA, SQL, GROOVY, SHELL, KOTLIN}
/**
* Enum defining the possible EL evaluation modes for configuration variables.
*/
public enum Evaluation {IMPLICIT, EXPLICIT}
/**
* Display mode for the configuration when authoring pipelines. When the pipeline designer tool is in BASIC
* display mode all ADVANCED configs are hidden. All ADVANCED configs must have a sensible default value.
* BASIC configs are shown always.
*
* The display mode is a UI gimmick only.
*/
public enum DisplayMode {
BASIC,
ADVANCED
}
/**
* Defines the upload capability for a configuration. NO means no upload configuration support. TEXT indicates
* a text payload can be uploaded to the property. BASE64 indicates a binary payload BASE64 encoded can be
* uploaded to the property.
*/
enum Upload { NO, TEXT, BASE64 }
/**
* The configuration type for the configuration variable.
*/
Type type();
/**
* The upload capability for the configuration.
*/
Upload upload() default Upload.NO;
/**
* The default value for the configuration variable. If the {@link #evaluation()} is
* {@link com.streamsets.pipeline.api.ConfigDef.Evaluation#IMPLICIT} the default value can be an EL and it will
* be resolved by the Data Collector at stage initialization time.
*
* If the variable itself has default value assigned, the default value set here is ignored.
*/
String defaultValue() default "";
/**
* Use instead of defaultValue to read a text resource in with UTF-8 as a String and use it as the defaultValue.
* Path must be relative to the directory within \resources corresponding to the enclosing ConfigDef's class package.
*/
String defaultValueFromResource() default "";
/**
* Indicates if a configuration value is required or not. This is enforced by the validation logic.
*/
boolean required();
/**
* The default label for the UI.
*/
String label();
/**
* The placeholder for the UI.
*/
Placeholder placeholder() default @Placeholder();
/**
* The default tooltip description for the UI.
*/
String description() default "";
/**
* The configuration group for the UI.
*
* If the configuration variable is within a configuration bean, instead hardcoding the group name it is possible
* to reference the group ordinal (using #N where N is the ordinal) of the groups defined in
* {@link ConfigDefBean} annotation of the configuration bean variable.
*
* @see ConfigDefBean
*/
String group() default "";
/**
* The display position in the UI.
*/
int displayPosition() default 0;
/**
* The name of the configuration this configuration depends on, if any.
*
* If it depends on another configuration, this configuration will be displayed only if the depends on
* configuration value matches one of the trigger values.
*
* If using {@link ConfigDefBean} configuration variables can be in different classes and at different depths.
* For these cases, if the depends on configuration variable is not in the same class as the configuration
* variable referring to it, use ^[CONFIGURATION NAME] to specify the full configuration name from the stage.
* Or use [CONFIGURATION NAME]^...^ to specify a relative configuration name, going back from the current
* configuration.
*
* @see #triggeredByValue()
*/
String dependsOn() default "";
/**
* The trigger values of the depends on configuration that activate this configuration.
*
* @see #dependsOn()
*
*/
String[] triggeredByValue() default {};
/**
* List of {@linkplain Dependency} instances that can specify the parameters and their respective trigger values that
* this configName depends on. Only if all of these dependencies match at least one of their respective
* trigger values will enable this config itself.
*
* @see Dependency
*/
Dependency[] dependencies() default {};
/**
* Indicates the minimum value for configuration variables of type {@link Type#NUMBER}.
*/
long min() default Long.MIN_VALUE;
/**
* Indicates the maximum value for configuration variables of type {@link Type#NUMBER}.
*/
long max() default Long.MAX_VALUE;
/**
* Indicates the number of lines in the UI for configuration variables of type {@link Type#TEXT}.
*
*
* - 0 - displays 1 line, the text box cannot re-size and it accepts only one line of input
* - 1 - displays 1 line, the text box can be re-size and it accepts multiple lines of
* - n - displays n lines, the text box can be re-size and it accepts only one line of input
*
*/
int lines() default 0;
/**
* Indicates the expected syntax for a configuration of type {@link Type#TEXT}. It is used by the UI to provide
* syntax highlighting.
*/
Mode mode() default Mode.PLAIN_TEXT;
/**
* Defines custom EL functions and constants available to EL evalutors of this configuration variable.
*
* @see ElFunction
* @see ElConstant
* @see com.streamsets.pipeline.api.Stage.ELContext
*/
Class[] elDefs() default {};
/**
* Indicates if the Data Collector evaluates ELs in the configuration and the stages sees the already resolved value
* (implicit), or if the Data Collector does not evaluate the EL and the stage must use a
* {@link com.streamsets.pipeline.api.el.ELEval} to explicitly perform the EL evaluation.
*/
Evaluation evaluation() default Evaluation.IMPLICIT;
/**
* Set to true if the stage is able to generate custom suggestions for this field.
*
* @return
*/
boolean stageSuggestions() default false;
/**
* Display mode for the configuration, defaults to BASIC (always shown).
*
* All ADVANCED configs must have a sensible default value. BASIC configs are shown always.
*
* The display mode is a UI gimmick only.
*/
DisplayMode displayMode() default DisplayMode.BASIC;
/**
* Indicates that this field is a "connection selection" field for a particular Connection Type
* (see {@link ConnectionDef#type()}. An empty-string value (default) indicates that it is not.
*/
String connectionType() default "";
/**
*
* If the stage uses explorer, set this property to TRUE to indicate the property is required
* for explorer to work (for example, it contains connection information required for
* explorer to retrieve data from the external system).
*
*/
boolean requiredForExplorerLoad() default false;
/**
*
* If the stage uses explorer, set this property to TRUE to indicate the property should be
* used to create the explorer ExplorerData key, if this value changes the ExplorerData changes.
* It is valid also if the property is empty (for example, it contains the role of the user in the external
* system, different roles gives different visibility to the external system).
*
*/
boolean useForExplorerLoad() default false;
/**
*
* If set, it defines how explorer will help the user to set the value for an
* explorer aware property.
*
*/
ExplorerConfigDef explorer() default @ExplorerConfigDef(
explorerId = "", explorerType = "", schemaElement = "",
binding = ExplorerConfigDef.Binding.NONE
);
/**
* List of {@linkplain Constraint} instances to specify subsets of possible values depending of values of other settings.
*
* @see Dependency
*/
Constraint[] constraints() default {};
}