CSVBeans -

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.

Project Documentation

Legend