com.delphix.masking.api.plugin

Interface MaskingAlgorithm<T>

Type Parameters:

T - The type of value this Algorithm masks

All Superinterfaces:

JsonConfigurable, MaskingComponent, PluginComponent

public interface MaskingAlgorithm<T>
extends MaskingComponent

This is the interface all Delphix Masking Algorithms must implement. The type parameter T must correspond to a class mentioned in the MaskingAlgorithm.MaskingType enumeration.

When algorithm type value MaskingAlgorithm.MaskingType.ADVANCED_OBJECT is used, the algorithm must be prepared to mask values of any other type, excluding MaskingAlgorithm.MaskingType.GENERIC_DATA_ROW. The actual type of the data passed may be determined by retrieving the value metadata using ComponentService.getMaskValueMetadata(), then calling MaskValueMetadata.getMaskingType(). Use of this algorithm type requires careful attention to Java type safety and is intended for developers comfortable handling explicit type conversions.

Attention! If using logger - be careful in choosing the logged information. The sensitive information (to be masked) should never be logged!

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	MaskingAlgorithm.MaskingMode Enumeration of supported masking modes for MaskingAlgorithm.
static class	MaskingAlgorithm.MaskingType Enumeration of all supported type parameter T values for MaskingAlgorithm.

Field Summary

Fields inherited from interface com.delphix.masking.api.plugin.MaskingComponent

IDENTIFIER_SCOPING_SEPARATOR

Method Summary

Modifier and Type	Method and Description
default java.lang.String	getConversionFallbackValue() Method to return a default conversion value used during type conversion exception handling.
default java.util.Map<java.lang.String,MaskingAlgorithm.MaskingType>	listMaskedFields() Deprecated. 1.9.0
default java.util.List<AlgorithmLogicalField>	listMultiColumnFields() This method is required for multi-column algorithm.
default java.util.Map<java.lang.String,MaskingAlgorithm.MaskingType>	listReadOnlyFields() Deprecated. 1.9.0
T	mask(T value) Method to mask a value of the specified type.
default void	maskBatch(MaskingBatch<T> batch) Method to mask a batch of values.
default void	setMaskingMode(MaskingAlgorithm.MaskingMode mode) Method to set the Masking Mode.

Methods inherited from interface com.delphix.masking.api.plugin.MaskingComponent

getAllowFurtherInstances, getDefaultInstances, setup, tearDown

Methods inherited from interface com.delphix.masking.api.plugin.PluginComponent

getDescription, getDocumentation, getName

Methods inherited from interface com.delphix.masking.api.plugin.JsonConfigurable

validate

Method Detail

mask

T mask(@Nullable
       T value)
throws MaskingException

Method to mask a value of the specified type. All algorithms must provide an implementation of this method, even if the maskBatch method below is implemented.

Attention! This method accesses the value to be masked. This sensitive information should never be logged!

Parameters:

value - The value to be masked.

Returns:

The masked value. In case of a GenericDataRow type, the returned value will be ignored. In that case the corresponding GenericData object should be modified.

Throws:

MaskingException - If an error occurs while masking.

maskBatch

default void maskBatch(@Nonnull
                       MaskingBatch<T> batch)

Method to mask a batch of values. This method need only be implemented if some aspect of algorithm performance can be significantly improved by masking a batch of values using a different approach. One example of this is when masking values by calling an external API, where working one value at a time would generate a large number of requests to the external API, resulting in poor performance. Otherwise, the default implementation is sufficient.

The execution framework will call either the mask or maskBatch method depending on the masking application. Masking results SHOULD be consistent regardless of which method is used to mask values.

Unlike the single-value mask method, errors (MaskingException objects) should be attached to the value in the batch that resulted in the exception, rather than thrown. Refer to MaskingBatch.setError(int, com.delphix.masking.api.plugin.exception.MaskingException). Whenever an error is reported, any value set using MaskingBatch.setError(int, com.delphix.masking.api.plugin.exception.MaskingException) with the same index is ignored.

Parameters:

batch - A batch containing the values to be masked.

Since:

1.5.0

listReadOnlyFields

@Deprecated
default java.util.Map<java.lang.String,MaskingAlgorithm.MaskingType> listReadOnlyFields()

Deprecated. 1.9.0

Method to list additional fields needed by an algorithm of type GenericDataRow. These fields are read only fields. This is an optional method for GenericDataRow algorithms. In the mask(T) method, these values will be provided in a GenericData object as part of GenericDataRow object.

Returns:

Map of name of fields and their types. The type can't be MaskingAlgorithm.MaskingType.GENERIC_DATA_ROW.

Since:

1.2.0

listMaskedFields

@Deprecated
default java.util.Map<java.lang.String,MaskingAlgorithm.MaskingType> listMaskedFields()

Deprecated. 1.9.0

Method to list the fields needed by an algorithm of type GenericDataRow for masking. These fields are supposed to be masked. This is required method for GenericDataRow algorithms. In the mask(T) method, these values will be provided in a GenericData object as part of GenericDataRow object. The GenericData object is for each of the field defined by this method. The actual data can be retrieved by calling the appropriate get method on that object.

Returns:

Map of name of fields and their types. The type can't be MaskingAlgorithm.MaskingType.GENERIC_DATA_ROW.

Since:

1.2.0

setMaskingMode

default void setMaskingMode(MaskingAlgorithm.MaskingMode mode)

Method to set the Masking Mode. This method must be overridden by any algorithm that wishes to support tokenization.

Parameters:

mode - the MaskingMode enum value.

Since:

1.6.0

getConversionFallbackValue

default java.lang.String getConversionFallbackValue()

Method to return a default conversion value used during type conversion exception handling. If returns null, then no fallback is defined and non-conformant data handling will proceed normally.

Returns:

the default conversion value

Since:

1.8.0

listMultiColumnFields

default java.util.List<AlgorithmLogicalField> listMultiColumnFields()

This method is required for multi-column algorithm. It allows the multi-column algorithm to describe the fields it expects to process. An algorithm is considered multi-column when its parameterized type is GenericDataRow. Each field in the return list must have a unique value for name, and at least one masked field (not read-only) must be defined that is not marked optional.

In the mask(T) method, these values will be provided in a GenericData object as part of GenericDataRow object. The GenericData object is for each of the field defined by this method. The actual data can be retrieved by calling the appropriate get method on that object. An algorithm that implements optional fields must be prepared to handle the case where the GenericDataRow get method returns null when an optional field is requested.

A default implementation is provided to support older multi-column algorithms that implement one or both of listMaskedFields() and listReadOnlyFields().

Returns:

A list of AlgorithmLogicalField objects describing each input field. The value for type can't be MaskingAlgorithm.MaskingType.GENERIC_DATA_ROW.

Since:

1.9.0