Home | Table of Contents | JavaBeanReader | CloverETL 4.6.1
--- | --- | ---
Prev | Readers | Next

## JavaBeanReader

# Not available in Community Designer

Short Description
Ports
Metadata
JavaBeanReader Attributes
Details
See also

### Short Description

JavaBeanReader reads a JavaBeans hierarchical structure which is stored in a dictionary. That allows dynamic data interchange between Clover graphs and external environment, such as cloud. The dictionary you are reading to serves as an interface between the outer (e.g. cloud) and inner worlds (Clover).

Component | Data source | Input ports | Output ports | Each to all outputs | Different to different outputs | Transformation | Transf. req. | Java | CTL | Auto-propagated metadata
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
JavaBeanReader | dictionary | 0 | 1-n |  |  |  |  |  |  |

### Icon

### Ports

Port type | Number | Required | Description | Metadata
--- | --- | --- | --- | ---
Output | 0 |  | Successfully read records. | Any
1-n | Connect other output ports if your mapping requires that. | Successfully read records. | Any. Each port can have different metadata.

### Metadata

JavaBeanReader does not propagate metadata.

JavaBeanReader has no metadata template.

### JavaBeanReader Attributes

Attribute | Req | Description | Possible values
--- | --- | --- | ---
Basic
Dictionary source | yes | The dictionary you want to read JavaBeans from. | Name of a dictionary you have previously defined.
Data policy |  | Determines what should be done when an error on reading occurs. See Data Policy for more information. | Strict (default) | Controlled | Lenient
Mapping | [1] | Mapping the input JavaBeans structure to output ports. See JavaBeanReader Mapping Definition for more information. |
Mapping URL | [1] | External text file containing the mapping definition. |
Implicit mapping |  | By default, you have to manually map input elements even to Clover fields of the same name. If you switch to `true`, JSON-to-Clover mapping on matching names will be performed automatically. That can save you a lot of effort in long and well-structured JSON files. See JSON Mapping - Specifics. | false (default) | true
[1] One of these has to be specified. If both are specified, Mapping URL has a higher priority.

### Details

JavaBeanReader reads data from JavaBeans through a dictionary. It maps Java attributes / collection elements to output records based on a mapping you define. You do not have to map the whole input file - you use XPath expressions to select only the data you need. The component sends data to different connected output records as defined by your mapping.

The mapping process is similar to the one in XMLReader.

#### JavaBeanReader Mapping Definition

1. Every Mapping definition consists of `<Context>` tags which contain also some attributes and allow mapping of element names to Clover fields. Nested structure of `<Context>` tags is similar to the nested structure of elements in input JavaBeans.

2. Each `<Context>` tag can surround a serie of nested `<Mapping>` tags. These allow to rename JavaBeans elements to Clover fields. However, Mapping does not need to copy the whole input structure, it can start at an arbitrary depth in the tree.

3. Each of these `<Context>` and `<Mapping>` tags contains some JavaBeanReader Context Tag Attributes and JavaBeanReader Mapping Tag Attributes, respectively.

   Example 48.4. Example Mapping in JavaBeanReader

       	<Context xpath="/employees" outPort="0" sequenceId="empSeq" sequenceField="id">
       		<Mapping xpath="firstName" cloverField="firstName"/>
       		<Mapping xpath="lastName" cloverField="lastName"/>
       		<Mapping xpath="salary" cloverField="salary"/>
       		<Mapping xpath="jobTitle" cloverField="jobTitle"/>
       		<Context xpath="children" outPort="1" parentKey="id" generatedKey="empID">
       			<Mapping xpath="name" cloverField="chname"/>
       			<Mapping xpath="age" cloverField="age"/>
       		</Context>
       		<Context xpath="benefits" outPort="2" parentKey="id" generatedKey="empID">
       			<Mapping xpath="car" cloverField="car"/>
       			<Mapping xpath="cellPhone" cloverField="mobilephone"/>
       			<Mapping xpath="monthlyBonus" cloverField="monthlyBonus"/>
       			<Mapping xpath="yearlyBonus" cloverField="yearlyBonus"/>
       		</Context>
       		<Context xpath="projects" outPort="3" parentKey="id" generatedKey="empID">
       			<Mapping xpath="name" cloverField="projName"/>
       			<Mapping xpath="manager" cloverField="projManager"/>
       			<Mapping xpath="start" cloverField="Start"/>
       			<Mapping xpath="end" cloverField="End"/>
       			<Mapping xpath="customers" cloverField="customers"/>
       		</Context>
       	</Context>

   | Important
   If you switch Implicit mapping to `true`, elements (e.g. `salary`) will be automatically mapped onto fields of the same name (`salary`) and you do not have to write:
       	    	<Mapping xpath="salary" cloverField="salary"/>
   and you map explicitly only to populate fields with data from distinct elements.

4. JavaBeanReader Context Tags and Mapping Tags

   - Empty Context Tag (Without a Child)

     `<Context xpath="xpathexpression"` JavaBeanReader Context Tag Attributes `/>`

   - Non-Empty Context Tag (Parent with a Child)

     `<Context xpath="xpathexpression"` JavaBeanReader Context Tag Attributes `>`

     `(nested Context and Mapping elements (only children, parents with one or more children, etc.)`

     `</Context>`

   - Empty Mapping Tag (Renaming Tag)

     - `xpath` is used:

       `<Mapping xpath="xpathexpression"` JavaBeanReader Mapping Tag Attributes `/>`

     - `nodeName` is used:

       `<Mapping nodeName="elementname"` JavaBeanReader Mapping Tag Attributes `/>`

5. JavaBeanReader Context Tag and Mapping Tag Attributes

   1) JavaBeanReader Context Tag Attributes

   - `xpath`

     Required

     The xpath expression can be any XPath query.

     Example: `xpath="/tagA/.../tagJ"`

   - `outPort`

     Optional

     Number of output port to which data is sent. If not defined, no data from this level of Mapping is sent out using such level of Mapping.

     Example: `outPort="2"`

   - `parentKey`

     Both `parentKey` and `generatedKey` must be specified.

     Sequence of metadata fields on the next parent level separated by semicolon, colon, or pipe. Number and data types of all these fields must be the same in the `generatedKey` attribute or all values are concatenated to create a unique string value. In such a case, key has only one field.

     Example: `parentKey="first_name;last_name"`

     Equal values of these attributes assure that such records can be joined in the future.

   - `generatedKey`

     Both `parentKey` and `generatedKey` must be specified.

     Sequence of metadata fields on the specified level separated by semicolon, colon, or pipe. Number and data types of all these fields must be the same in the `parentKey` attribute or all values are concatenated to create a unique string value. In such a case, key has only one field.

     Example: `generatedKey="f_name;l_name"`

     Equal values of these attributes assure that such records can be joined in the future.

   - `sequenceId`

     When a pair of `parentKey` and `generatedKey` does not insure unique identification of records, a sequence can be defined and used.

     Id of the sequence.

     Example: `sequenceId="Sequence0"`

   - `sequenceField`

     When a pair of `parentKey` and `generatedKey` does not insure unique identification of records, a sequence can be defined and used.

     A metadata field on the specified level in which the sequence values are written. Can serve as `parentKey` for the next nested level.

     Example: `sequenceField="sequenceKey"`

   2) JavaBeanReader Mapping Tag Attributes

   - `xpath`

     Either `xpath` or `nodeName` must be specified in `<Mapping>` tag.

     XPath query.

     Example: `xpath="tagA/.../salary"`

   - `nodeName`

     Either `xpath` or `nodeName` must be specified in `<Mapping>` tag. Using `nodeName` is faster than using `xpath`.

     JavaBeans node that should be mapped to Clover field.

     Example: `nodeName="salary"`

   - `cloverField`

     Required

     Clover field to which JavaBeans node should be mapped.

     Name of the field in the corresponding level.

     Example: `cloverFields="SALARY"`

#### Reading Multivalue Fields

As of Clover 3.3, reading multivalue fields is supported - you can read only lists, however (see Multivalue Fields).

| Note
Reading maps is handled as reading pure `string` (for all data types as map's values).

Example 48.5. Reading lists with JavaBeanReader

An example input file containing e.g. a list of three elements: `John, Vicky, Brian`

can be read back by the component with this mapping:

        <Mapping xpath="attendees" cloverField="attendanceList"/>

where `attendanceList` is a field of your metadata. The metadata has to be assigned to the component's output edge. After you run the graph, the field will get populated by data like this (that what you will see in View data):

`[John,Vicky,Brian]`

#### Data conversions in JavaBeanReader

The possible conversions of java data types to CTL2 data types are described in the following table.

The list in the table means list of corresponding data type.

Table 48.6. Java data type to CTL2 data type conversion

Java data types | CTL2 data types
--- | ---
Numeric data types | boolean | date | byte | cbyte | String | list | map
integer | long | number (double) | decimal
int |  |  |  |  | - |  | - | - |  |  |
long | - |  |  | - | - |  | - | - |  |  |
float | - | - |  | - |  |  | - | - |  |  |
double | - | - |  | - |  |  | - | - |  |  |
boolean |  |  |  |  |  |  | - | - |  |  |
java.util.Date |  |  |  |  |  |  | - | - |  |  |
String | - | - | - | - | - |  | - | - |  |  |
array [] | - | - | - | - | - |  | - | - | - | - |
java.util.Collection | - | - | - | - | - |  | - | - | - |  |

Conversions need to be explained follow:

##### Java int to CTL2 boolean

Value 0 is converted to `false`, 1 is converted to `true`. If java `int` contains other value, graph fails.

##### Java int to CTL2 byte or cbyte

Value of `int` variable is converted either to character or to empty string.

##### Java long to CTL2 integer

Value of java bean `long` variable can be read to `integer` field provided the value is within the range of CTL2 `integer`. If the value is out of the range of CTL2 `integer`, graph fails.

##### Java long to CTL2 decimal

The `decimal` needs to have sufficient length to contain value from `long` data type. The default length (12) might not be enough for all cases.

##### Java long to CTL2 boolean

The conversion from java `long` to CTL2 `boolean` works in the same way as conversion from java `int` to CTL2 `boolean`. 0 is converted to `false`, 1 is converted to `true`, other values cause failure.

##### Java long to CTL2 byte or cbyte

See: Java `int` to CTL2 `byte` or `cbyte` conversion.

##### Java float to CTL2 integer

Value of java `float` variable can be converted to CTL2 `integer`. Value of the `float` number is being truncated in the conversion. If the value in `float` variable is out of the range of `integer`, conversion fails.

##### Java float to CTL2 long

Value of java `float` variable can be converted to CTL2 `long`. The value of `float` number is being truncated. If the value stored in float variable is positive and out of the range of `long` data type, the nearest `long` value is used. If the value stored in float variable is negative and out of the range of `long` data type, the result is `null`.

##### Java float to CTL2 decimal

CTL2 `decimal` needs to have sufficient length. If not, the conversion from java `float` fails.

##### Java float to CTL2 byte and cbyte

Value of java `float` is trimmed to it's integral part and the result value is converted to character. If the value is out of the range of `byte`, empty string is used.

##### Java double to CTL2 integer

Value of java `double` needs to be within the range of CTL2 `integer`. The value of java `double` is truncated to it's integral part towards zero. If the value is out of the range, conversion fails.

##### Java double to CTL2 long

If the value of java `double`is within the range of CTL2 `long`, the value is truncated to nearest integral value towards zero. If the value of java `double` is positive and out of the range of CTL2 `long`, the result is the largest `long` number (`Long.MAX_VALUE`). If the value of java `double` is negative and out of the range of CTL `long`, the result is `null`.

##### Java double to CTL2 decimal

The CTL2 `decimal` needs to have sufficient length to contain value of java `double`. In case of insufficient length of CTL2 `decimal` the conversion fails.

##### Java double to CTL2 byte and cbyte

Value of java `double` is trimmed to it's integral part and the result is converted to character. If the value is out of the range of `byte`, empty string is used.

##### Java boolean to CTL2 byte and cbyte

Value of java `boolean` converted to CTL2 `byte` or `cbyte` is single unprintable character. The character has code `0` if the input is `false` or `1` if the input is `true`.

##### Java Date to CTL2 byte and cbyte

Value of java `Date` converted to `byte` or `cbyte` results in empty string.

##### Java String to CTL2 integer or long

If the java `String` variable contains integral value within the range of `integer`, the number will be converted. Otherwise conversion fails.

If the java `String` variable contains integral value within the range of `long`, the number will be converted to the `long`. Otherwise conversion fails.

##### Java String to CTL2 number (double) or decimal

If the java `string` contains numeric value, the value is converted to `number` (`double`) or `decimal`. If the java `string` does not contain numeric value, the conversion fails.

##### Java String to CTL2 boolean

If java `String` contains value `1`, `true`, `True` or `TRUE`, CTL2 `boolean` will hold `true`. If java `String` contains value `0`, `false`, `False` or `FALSE`, CTL2 `boolean` will hold `false`. If any other value is present in the java `String`, conversion fails.

##### Java String to CTL2 byte or cbyte

Java `String` to `byte` or `cbyte` conversion has empty string as result.

##### Java array to CTL2

Conversion of java bean array to `integer`, `long`, `number` (`double`) and `decimal` has zero as result.

The result of conversion from java array CTL2 `boolean` is `false`.

Java array converted to `byte` and `cbyte` is `null`.

##### Java Collection to CTL2

Conversion from java `Collection` to `integer`, `long`, `double`, `decimal`, `string` returns first item of collection.

`Collection` to `byte` and `cbyte` conversion has empty string as a result.

### See also

Data Types in CTL2
Data Types in Metadata
JavaBeanWriter
Common Properties of Components
Specific Attribute Types
Common Properties of Readers
Readers Comparison

Prev | Up | Next
HadoopReader | Home | Table of Contents | JMSReader