com.univocity.parsers.annotations.Parsed Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of univocity-parsers Show documentation
univocity's open source parsers for processing different text formats using a consistent API
There is a newer version: 2.9.1
/*******************************************************************************
 * Copyright 2014 uniVocity Software Pty Ltd
 *
 * 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.univocity.parsers.annotations;

import java.lang.annotation.*;

import com.univocity.parsers.annotations.helpers.*;
import com.univocity.parsers.common.processor.*;
import com.univocity.parsers.conversions.*;

/**
 * Indicates the field is parsed. If the annotated field type is not a String, it will be automatically converted using one
 * of the existing {@link Conversion} implementations in package {@link com.univocity.parsers.conversions}.
 *
 *
 * Commonly used for java beans processed using {@link BeanProcessor} and/or {@link BeanWriterProcessor}
 * 
Implementation note: All annotations in @Parsed fields are processed by {@link AnnotationHelper}
 *
 * @see Conversion
 * @see Conversions
 * @see BeanProcessor
 * @see BeanWriterProcessor
 * @see AnnotationHelper
 *
 * @author uniVocity Software Pty Ltd - [email protected]
 *
 */
@Retention(RetentionPolicy.RUNTIME)
@Inherited
@Target(value = { ElementType.FIELD, ElementType.METHOD })
public @interface Parsed {
	/**
	 * The field name in a parsed record
	 * @return the field name (optional if the index is provided)
	 */
	String field() default "";

	/**
	 * Field position in a parsed record
	 * @return the position of this field (optional if the field name is provided)
	 */
	int index() default -1;

	/**
	 * The default value to assign to this field in the parsed value is null
	 * 
The String literal "null" will be interpreted as a regular null.
	 * 
Use "'null"' if you want the default value to be the string "null"
	 *
	 * 
this value will have different effects depending on the field type:
	 * 

	 * 	on fields of type {@link java.util.Date} or {@link java.util.Calendar}: if the null value is "now", the result of new Date() or Calendar.getInstance() will be used.
	 *  
on numeric fields (primitives, wrappers and {@link java.math.BigDecimal} and {@link java.math.BigInteger}): if the null value contains a number, e.g. "50.01", it will be parsed and assigned to the field.
	 *  
on boolean and Boolean fields: if the null value contains a String, the result of Boolean.valueOf(defaultNullRead()) will assigned to the field.
	 *  
on char and Character fields: if the null value contains a String, the result of defaultNullRead().charAt(0) will assigned to the field.
	 *      An exception will be thrown if the length of this String is different than 1
	 * 
	 *
	 * @return the default String to return when the parsed value is null
	 */
	String defaultNullRead() default "null";

	/**
	 * The default value to read from this field if it is null. Used for writing to an output by {@link BeanWriterProcessor}.
	 * The String literal "null" will be interpreted as a regular {@code null}.
	 * Use "'null"' if you want the default value to be the string {@code "null"}
	 *
	 * @return default String to write when the input is null.
	 */
	String defaultNullWrite() default "null";
}