Specifications File Reference

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>

		

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.

Element Description Required
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

property

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:

Attribute Description Required
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 record and session No

Here is a list of the properties used by csvBeans:

Property Description Default
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 property element is then used within the strategy element. The parsers shipped with csvBeans have the following properties that can be modified through the specifications file:

Property Description Default
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

strategy

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.

Element Description Required
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

parser

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.

Attribute Description Required
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.

listener

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:

Attribute Description Required
className Specify the name of the listener implementation. Yes

builder

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.

Attribute Description Required
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.

record

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.

Attribute Description Required
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.

Element Description Required
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.

field

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:

Attribute Description Required
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:

Element Description Required
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

converter

This element is used within the field element or within the csvbeans element.

Attributes Description Required
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

validators

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.

Element Description Required
validator Define the validator you want to associate with the field Yes

validator

Define one validator

Attribute Description Required
className Define the class of the validator. The validator must implement the org.csvbeans.validators.Validator interface. Yes

authorized-values

This element is used within the field element. It can only have children:

Element Description Required
value The authorized value in the field. There must be one or several value elements. Yes

value

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.

bean

This element looks like the field element but is used to define a Java bean type. Here is the list of this element attributes:

Attribute Description Required
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.