com.streamsets.pipeline.api.ExplorerConfigDef Maven / Gradle / Ivy
/*
* Copyright 2023 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;
/**
*
* Defines how explorer will help the user to set the value for an explorer
* aware property. Annotates a {@code @ConfigDef} property as metadata explorer
* aware.
*
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface ExplorerConfigDef {
String label() default "";
String description() default "";
/**
*
* The explorer ID that identifies the explorer view used by a configuration.
*
*
* A stage as a single explorer, but it may have multiple views.
*
*
* For example a DB explorer may have a view to select DB/SCHEMA/TABLE and
* another view to select TABLE/COLUMNS.
*
*
* The explorer ID identifies the configurations filled in by an explorer view.
*
*/
String explorerId();
/**
* A stage or pipeline may use system explorers of different types.
* To invoke an explorer to set a configuration property we need to know which one of the explorers we should use.
*
* @return explore type.
*/
String explorerType();
/**
*
* Next explorer ID, for UI navigation purposes.
*
*/
String nextExplorer() default "";
/**
*
* Defines the type of explorer binding the configuration has.
*
*/
enum Binding {
/**
*
* A configuration with {@code DRIVER} binding can trigger an explorer
* search, and it is filled in with the searched 'schemaElement'.
*
*/
DRIVER,
/**
*
* A configuration with {@code DRIVER_PARENT} binding is filled with the
* corresponding 'schemaElement' from the explorer search selection done
* by the {@code DRIVER} configuration (same explorer ID).
*
*/
DRIVER_PARENT,
/**
*
* A configuration with {@code DRIVEN} binding will do a search
* restricting the search domain to the current values for the
* configurations with {@code DRIVER} and {@code DRIVER_PARENT}
* bindings with the same explorer ID.
*
*/
DRIVEN,
/**
*
* A configuration that has a schema element only to be used to fix
* schema elements in explorer searches.
*
*/
NONE
}
Binding binding();
/**
*
* Used to specify additional configs to schemaElement bindings when the
* binding config are {@code DRIVER} or {@code DRIVEN}.
*
*
* The specified configs must have an {@code ExplorerConfigDef} as the
* 'schemaElement' name it will be inferred from it.
*
*
* There specified configs may have a different explorer ID.
*
*
* If there are multiple configs with the same 'schemaElement', the explorer
* search should use the first non-empty value to fix the search.
*
*/
String[] additionalDrivenBindings() default {};
/**
* Used to specify the configs that should be used to position on the result tree. DRIVER_PARENT configs are
* automatically added.
* If there is more than one config that reference the same schema, the Explorer UI should use the first non-blank one as
* positioning value.
*/
String[] additionalPositionAt() default {};
/**
*
* Name of the metadata explorer schema element Explorer UI should let the
* user select for this configuration.
*
*/
String schemaElement();
/**
* This is a list of attribute names of the schema element.
* The frontend should show attribute values along with their labels in the order of the list.
* This parameter affects how the configuration is displayed on the stage/pipeline config tab.
* By convention, the frontend always show the value (without its label) of the ExplorerSchema.Element.NAME_ATTR attribute.
* Adding that attribute to the list makes the value of that attribute to be show again along with its label.
*/
String[] configSchemaAttributes() default {};
/**
* This is a list of attribute names of the schema element.
* The frontend should show attribute values along with their labels in the order of the list.
* This parameter defines how objects are shown in the system explorer dialog.
* By convention, the frontend always show the value (without its label) of the ExplorerSchema.Element.NAME_ATTR attribute.
* Adding that attribute to the list makes the value of that attribute to be show again along with its label.
*/
String[] explorerSchemaAttributes() default {};
/**
*
* Location defines where Explorer UI should place, in a configuration, an
* explorer chosen value.
*
*/
enum Location { PROPERTY, MAP_KEY, MAP_VALUE, LIST_MULTI_VALUE }
/**
*
* Where Explorer UI should set the Explorer chosen value in the configuration.
*
*
* For {@code Map} properties it should be set to {@code MAP_KEY} or {@code MAP_VALUE}
* to indicate where the value should be set.
*
*
* For {@code List} properties, if set to {@code PROPERTY}, explorer should open once per list element,
* allow a single selection, and put the value in the selected element.
*
*
* For {@code List} properties, if set to {@code LIST_MULTI_VALUE}, explorer should open one for the list,
* allow multiselection and put each selection in a different list element.
*
*
* For other {@code List} properties, if set to {@code LIST_MULTI_VALUE}, explorer should open one for the list,
* allow multiselection and put each selection in a different list element, on the path indicated by locationPath.
*
* For all other configs it should always be set to {@code PROPERTY}, the default.
*
*/
Location location() default Location.PROPERTY;
/**
*
* When location is set to {@code LIST_MULTI_VALUE}, the path where the Explorer chosen value should be set inside
* each object of the list.
*
*/
String locationPath() default "";
/**
*
* If Explorer UI should up truncate the results to start at the level of the
* searched schema element. For example if searching DB columns ...
*
*
* If upTruncateResult=false the result tree would be root->DB->SCHEMA->TABLE->COLUMNS.
*
*
* If upTruncateResult=true the result tree would have just root->COLUMNS.
*
*/
boolean upTruncateResult() default false;
/**
*
* How many levels of children elements of the schema element being searched
* should be displayed by Explorer UI. For example if the result is for
* 'database' schemaElement and additionalDepth=1 it would return also the
* schemas under each database giving more context to the user.
*
*/
int additionalDepth() default 0;
}