This is a reference for the specifications file used by the parsers.
<csvbeans> <property /> <converters> <converter> <property /> </converter> </converters> <strategy> <parser> <listener /> <property /> </parser> <builder> <property /> </builder> </strategy> <record> <field> <validators> <validator /> </validators> <converter /> <authorized-values> <value /> </authorized-values> </field> <bean> <field /> <bean /> </bean> </record> </csvbeans>
The <csvbeans> element is the root element of the specifications file. It needs no attribute. The following table lists all the possible children of this element.
|strategy||The strategies to use to parse or build a CSV file. csvBeans ships with different parsers and builders, and it is possible to create your own.||No|
|record||Describes a CSV record of the files to parse or build.||Yes|
This element allows to define properties that are used by csvBeans to perform some choices during the parsing or the building of CSV files. Here are the attributes of this element:
|name||The name of the property||Yes|
|value||The value of the property||Yes|
|scope||The scope of the property. It is used within context managements.
Authorized values are
Here is a list of the properties used by csvBeans:
|endingSeparator||Specify if a CSV line ends with a separator or not||false|
|saveEmptyTokens||Specify that empty values in the CSV file must be mapped with empty strings instead of null string||false|
|separator||Define the CSV separator of the file.||;|
|noStartTag||Define that the CSV file has no start tags. It implies that only one record maps with each CSV line.||false|
Parsing and building strategies can also have properties. The
|enableBeanStorage||Specify that the beans that are read during the parsing must be stored within the parsers. If you set it to false, you will not be able to get the beans from the getBeans method. You may set it to false when you parse the CSV files through a listener and you need to reduce memory usage.||true|
|continueParsingIfErrors||Specify that the parsing of the CSV file must continue even if errors have been processed||false|
Here you can define a parser or/and a builder to use. This element takes no attribute. The following table lists all the possible children of this element.
|parser||Defines the CSV parser to use in association with the specifications file.||No|
|builder||Defines the CSV builder to use in association with the specifications file.||Yes|
This element defines the CSV parser to use in association with the specifications file. It can be used if you don't want your code depending on a parsing implementation. The following table lists the attributes of this element.
|className||Define the type of the parser.csvBeans ships with several parsers: org.csvbeans.parsers.CSVParser1, org.csvbeans.parsers.CSVParser2 and org.csvbeans.parsers.CSVParser3 but you can define your own parser (it will have to implement the org.csvbeans.interfaces.parsers.ParsingStrategy interface)||Yes|
The element can have property elements that define the properties of the parser. See the property section for more info.
It is also possible to associate a listener to the parser thanks to the listener element.
This element allows to associate a listener object to the parsing strategy. The listener will be notified of several events that occur during the parsing. It must be an implementation of the CSVParserListener interface. The listener elements specifies the implementation to use for the parsing. It can only have one attribute:
|className||Specify the name of the listener implementation.||Yes|
This element defines the CSV builder to use in association with the specifications file. It can be used if you don't want your code depending on a building implementation. The following table lists the attributes of this element.
|className||Define the type of the parser.csvBeans ships with several builders: org.csvbeans.builders.CSVBuilder1 and org.csvbeans.builders.CSVBuilder3 but you can define your own parser (it will have to implement the org.csvbeans.interfaces.builders.BuildingStrategy interface)||Yes|
The element can have property elements that define the properties of the builder. See the property section for more info.
This element contains a description of a CSV record. Usually, a CSV record is a line of your CSV file but it could be several or a column or whateverelse if you implement your own parsing and building strategy. The following table lists the possible attributes of this element.
|className||Defines the Javabean that will contain the different fields of the record.||Yes|
|start||Defines a tag that identifies where the record begins in the CSV file.||Yes|
The following table lists all the possible children of the element.
|field||Associates a field of the CSV file with a simple property of the Javabean representing the record.||No|
|bean||Associates one or more fields of the CSV file with a bean property of the Javabean representing the record.||No|
These elements can be in any order within the <record> element.
This element defines the properties of a simple type Java attribute. By simple type, I mean simple Java types like int, float, Integer, String, Date and so on types. The following table lists the available attributes for this XML element:
|name||The name of the Java property that maps with the field||Yes|
|maxLen||The maximum length that the value can have in the CSV field. Default value: 10||No|
|listElement||Boolean that specifies that the field value is part of a list. The listSize attribute is required when this one is used. Default: false||No|
|listSize||Define the number of items in the list. Must be used when the listElement attribute is used.||No|
|required||Define if the value is required in the CSV field or not. Default: false||No|
|truncate||Boolean that specifies if the field value must be troncated when its length is bigger than the specified maximum length value. It only works with building strategies. Default: false||No|
|saveEmptyToken||Boolean that specifies if an empty string must be saved or considered like a new value.||No|
The field attribute can also contain the following elements:
|validators||List of validators that will check the field value||No|
|converter||Define or references a converter for the field value||No|
|authorized-values||List the values that the field can have||No|
This element is used within the field element or within the csvbeans element.
|id||Identified the converter, so it can be referenced elsewhere thanks to the attribute||Yes if ref attribute is not used|
|ref||References the id of an already defined converter. The converter must be defined before referencing it in the specifications file||Yes if id attribute is not used|
|className||The converter class. It must implement the org.csvbeans.converters.Converter interface.||Yes if id attribute is used|
This element can be used to associate a field with a list of validators that will check its value during the parsing or building of the field.
|validator||Define the validator you want to associate with the field||Yes|
Define one validator
|className||Define the class of the validator. The validator
must implement the
This element is used within the field element. It can only have children:
|value||The authorized value in the field. There must be one or several value elements.||Yes|
This element contains the authorized value. For example:
<authorized-values> <value>1</value> <value>2</value> </authorized-values>
It means that the 1 and the 2 values are the values that the field can have. The field cannot have any other value, otherwise an exception will be thrown during the parsing or the building of a CSV file.
This element looks like the field element but is used to define a Java bean type. Here is the list of this element attributes:
|name||The name of the Java property associated with the bean||Yes|
|className||Define the Java type of the bean.||Yes|
|listElement||Specify that the beans are stored within a list. Default: false||No|
|listSize||Specify the size of the list that the bean belongs to. Must be used when the listElement attribute is set to true||No|
This element can contain a mix of bean and field elements.