org.unitils.io.annotation.FileContent Maven / Gradle / Ivy
/*
* Copyright 2011, Unitils.org
*
* 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 org.unitils.io.annotation;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Annotation for loading the contents of a file into a field.
*
* The @FileContent will try to load a file (or other resource depending on the ReadingStrategy), convert it to the
* type of the annotated field and inject the result into the field.
*
* A file name can be specified as value explicitly. If no file name is specified, a default file name will be used:
* 'classname'.'extension'. The extension depends on the target type: 'txt' for String and 'properties' for Properties.
*
* By default, the file name is prefixed with the package name (. replaced by /).
* E.g. MyFile.xml becomes com/myPackage/MyFile.xml
*
* If a file name starts with a / it will not be prefixed with the package name.
* E.g. /MyFile.xml remains /MyFile.xml
*
* Package name prefixing can be disabled using the IOModule.file.prefixWithPackageName property.
* IOModule.file.prefixWithPackageName=false => MyFile.xml remains MyFile.xml
*
* If a path prefix is specified using the IOModule.file.pathPrefix property it is added to the file name.
* Examples:
*
* IOModule.file.pathPrefix=myPathPrefix: MyFile.xml becomes myPathPrefix/com/myPackage/MyFile.xml
* IOModule.file.pathPrefix=myPathPrefix: /MyFile.xml becomes myPathPrefix/MyFile.xml
*
* If the path prefix starts with '/', the file name is treated absolute, else it will be treated relative to the classpath.
*
* Examples:
*
* path prefix /c:/testfiles --> looks for c:/testfiles/MyFile.xml on the file system
* path prefix testfiles --> looks for testfiles/MyFile.xml on the classpath
*
* Example usage:
*
* public class MyTestClass extends UnitilsJUnit4 {
*
* ' @FileContent
* private String field1;
* ' @FileContent("/someFile.properties")
* private Properties field2;
* ...
* }
*
* In this example the content of 'org/mypackage/MyTestClass.txt" will be injected into field1 and the properties loaded from
* 'someFile.properties' will be injected into field2.
*
* The encoding of the file can be passed as an argument. By default ISO-8859-1 is used. The default can be set by
* overriding the IOModule.encoding.default property.
*
*
* @author Jeroen Horemans
* @author Tim Ducheyne
* @author Thomas De Rycke
* @since 3.3
*/
@Target(FIELD)
@Retention(RUNTIME)
public @interface FileContent {
/**
* @return File location of a file, this can be relative to the workspace, or an absolute path.
*/
String value() default "";
/**
* Encoding to be used when reading the file. If no encoding is specified
* the default JVM encoding will be used
*
* Possible values:
*
*
* Charset
* Description
* US-ASCII Seven-bit ASCII, a.k.a. ISO646-US, a.k.a. the Basic Latin block of the Unicode character set
* ISO-8859-1 ISO Latin Alphabet No. 1, a.k.a. ISO-LATIN-1
* UTF-8 Eight-bit UCS Transformation Format
* UTF-16BE Sixteen-bit UCS Transformation Format, big-endian byte order
* UTF-16LE Sixteen-bit UCS Transformation Format, little-endian byte order
* UTF-16 Sixteen-bit UCS Transformation Format, byte order identified by an optional byte-order mark
*
*
* @return encoding
*/
String encoding() default "";
}