net.sf.eBus.messages.EStringInfo Maven / Gradle / Ivy

Go to download
//
// Copyright 2019 Charles W. Rapp
//
// 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 net.sf.eBus.messages;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.nio.charset.Charset;

/**
 * This field-level, run-time annotation is used to define the
 * {@link Charset} used to serialize/de-serialize the associated
 * {@code String} field. If this annotation is not defined for
 * a string type, then
 * {@link net.sf.eBus.messages.type.DataType#CHARSET} is used.
 * 
 * A second attribute is line count. This specifies the number
 * of line separators expected in the {@code String}. This value
 * defaults to one if not specified. The message string does not
 * necessarily need to match this line count expect by an
 * application to enforce message correctness. This attribute may
 * be used in a GUI application to decide whether to use a JavaFX
 * {@code TextField} to input a single line string or a
 * {@code TextArea} for a multi-line string. If multi-line then
 * the line count may be used to define the {@code TextArea}
 * size.
 * 
 * 
 * This annotation is ignored if applied to a non-{@code String}
 * field.
 * 
 *
 * @author Charles W. Rapp
 */

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
@Documented
public @interface EStringInfo
{
    /**
     * Returns the name of the character set used to
     * serialize/de-serialize the {@code String} field. This
     * name must satisfy {@link Charset#forName(String)} and
     * return a character set instance. If this does not happen,
     * then {@link net.sf.eBus.messages.type.DataType#CHARSET}
     * is used.
     * @return character set name.
     */
    String charset() default "UTF_8";

    /**
     * Returns the expected number of lines in this message text
     * field. If not specified, then defaults to one.
     * @return text field line expected line count.
     */
    int lineCount() default 1;
} // end of annotation EStringInfo