org.refcodes.codec.BaseBuilder Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of refcodes-codec Show documentation
Show all versions of refcodes-codec Show documentation
Artifact with encoding and decoding (not in terms of encryption/decryption)
implementations (codecs) such as BASE64 encoding / decoding.
// /////////////////////////////////////////////////////////////////////////////
// REFCODES.ORG
// /////////////////////////////////////////////////////////////////////////////
// This code is copyright (c) by Siegfried Steiner, Munich, Germany and licensed
// under the following (see "http://en.wikipedia.org/wiki/Multi-licensing")
// licenses:
// -----------------------------------------------------------------------------
// GNU General Public License, v3.0 ("http://www.gnu.org/licenses/gpl-3.0.html")
// -----------------------------------------------------------------------------
// Apache License, v2.0 ("http://www.apache.org/licenses/LICENSE-2.0")
// -----------------------------------------------------------------------------
// Please contact the copyright holding author(s) of the software artifacts in
// question for licensing issues not being covered by the above listed licenses,
// also regarding commercial licensing models or regarding the compatibility
// with other open source licenses.
// /////////////////////////////////////////////////////////////////////////////
package org.refcodes.codec;
import org.refcodes.codec.BaseMetricsAccessor.BaseCodecMetricsProperty;
import org.refcodes.codec.BaseMetricsAccessor.BaseMetricsBuilder;
/**
* The {@link BaseBuilder} provides the functionality to do base encoding and
* decoding such as done by the Base64 encoding and decoding functionality (see
* "https://en.wikipedia.org/wiki/Base64"). The {@link BaseBuilder} makes use of
* the utility-Builder-Pattern and is designed to support codes starting with
* Base2 till Base64 and further up.
*/
public interface BaseBuilder extends BaseCodecMetricsProperty, BaseMetricsBuilder {
/**
* {@inheritDoc}
*/
@Override
default BaseBuilder withBaseMetrics( BaseMetrics aBaseMetricsCodec ) {
setBaseMetrics( aBaseMetricsCodec );
return this;
}
/**
* Sets the number base for the number base property.
*
* @param aNumberBase The number base to be stored by the base codec metrics
* property.
*/
default void setBaseMetrics( int aNumberBase ) {
setBaseMetrics( BaseConfig.toBaseCodec( aNumberBase ) );
}
/**
* Sets the number base for the number base property.
*
* @param aNumberBase The number base to be stored by the base codec metrics
* property.
*
* @return The builder for applying multiple build operations.
*/
default BaseBuilder withBaseMetrics( int aNumberBase ) {
setBaseMetrics( aNumberBase );
return this;
}
/**
* Retrieves the encoded text from the encoded text property.
*
* @return The encoded text stored by the encoded text property.
*/
String getEncodedText();
/**
* Retrieves the encoded text calculated from the decoded data.
*
* This method is to be side effect free in terms of the decoded data (and
* the encoded result) is not part of the state for this instance (from the
* point of view of this method). Still changing for example the
* {@link BaseMetrics} via {@link #withBaseMetrics(BaseMetrics)} can cause
* side effects!
*
* For avoiding thread race conditions / side effects regarding the decoded
* data (and the encoded result), use this method instead of the combination
* of {@link #withDecodedData(byte[])} with {@link #getEncodedText()}
*
* @param aDecodedData The decoded data to be encoded.
*
* @return The encoded text calculated from the decoded data.
*/
String toEncodedText( byte[] aDecodedData );
/**
* Retrieves the encoded text calculated from the decoded data.
*
* This method is to be side effect free in terms of the decoded data (and
* the encoded result) is not part of the state for this instance (from the
* point of view of this method). Still changing for example the
* {@link BaseMetrics} via {@link #withBaseMetrics(BaseMetrics)} can cause
* side effects!
*
* For avoiding thread race conditions / side effects regarding the decoded
* data (and the encoded result), use this method instead of the combination
* of {@link #withDecodedData(byte[])} with {@link #getEncodedText()}
*
* @param aDecodedData The decoded data to be encoded.
*
* @return The encoded text calculated from the decoded data.
*/
String toEncodedText( long aDecodedData );
/**
* Sets the encoded text for the encoded text property.
*
* @param aEncodedText The encoded text to be stored by the encoded text
* property.
*/
void setEncodedText( String aEncodedText );
/**
* Sets the encoded text for the encoded text property.
*
* @param aEncodedText The encoded text to be stored by the encoded text
* property.
*
* @return The builder for applying multiple build operations.
*/
default BaseBuilder withEncodedText( String aEncodedText ) {
setEncodedText( aEncodedText );
return this;
}
/**
* Retrieves the decoded data from the decoded data property.
*
* @return The decoded data stored by the decoded data property.
*/
byte[] getDecodedData();
/**
* Retrieves the decoded data calculated from the provided encoded text.
*
* This method is to be side effect free in terms of the encoded text (and
* the decoded result) is not part of the state for this instance (from the
* point of view of this method). Still changing for example the
* {@link BaseMetrics} via {@link #withBaseMetrics(BaseMetrics)} can cause
* side effects!
*
* For avoiding thread race conditions / side effects regarding the encoded
* text (and the decoded result), use this method instead of the combination
* of {@link #withEncodedText(String)} with {@link #getDecodedData()}.
*
* @param aEncodedText The encoded text to be decoded.
*
* @return The decoded data decoded from the encoded text.
*/
byte[] toDecodedData( String aEncodedText );
/**
* Sets the decoded data for the decoded data property.
*
* @param aDecodedData The decoded data to be stored by the decoded data
* property.
*/
void setDecodedData( byte[] aDecodedData );
/**
* Sets the decoded data for the decoded data property.
*
* @param aDecodedData The decoded data to be stored by the decoded data
* property.
*/
void setDecodedData( long aDecodedData );
/**
* Sets the decoded data for the decoded data property.
*
* @param aDecodedData The decoded data to be stored by the decoded data
* property.
*
* @return The builder for applying multiple build operations.
*/
default BaseBuilder withDecodedData( byte[] aDecodedData ) {
setDecodedData( aDecodedData );
return this;
}
/**
* Sets the decoded data for the decoded data property.
*
* @param aDecodedData The decoded data to be stored by the decoded data
* property.
*
* @return The builder for applying multiple build operations.
*/
default BaseBuilder withDecodedData( long aDecodedData ) {
setDecodedData( aDecodedData );
return this;
}
}