Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/smooks/smooks-fixed-length-cartridge

Smooks Fixed Length Cartridge
https://github.com/smooks/smooks-fixed-length-cartridge

fixed-length smooks-cartridge

Last synced: about 2 months ago
JSON representation

Smooks Fixed Length Cartridge

Awesome Lists containing this project

README 

        
= Smooks Fixed-Length Cartridge



image:https://img.shields.io/maven-central/v/org.smooks.cartridges/smooks-fixed-length-cartridge[Maven Central]

image:https://img.shields.io/nexus/s/org.smooks.cartridges/smooks-fixed-length-cartridge?server=https%3A%2F%2Foss.sonatype.org[Sonatype Nexus (Snapshots)]

image:https://github.com/smooks/smooks-fixed-length-cartridge/workflows/CI/badge.svg[Build Status]



// tag::smooks-fixed-length-cartridge[]

A simple/basic fixed-length reader configuration:



.smooks-config.xml

[source,xml]

----

  

  



    

      



----



Example input file:



....

#HEADER  

Tom       Fennelly  M 21 IE  

Maurice  Zeijen     M 27 NL

....



The above configuration will generate an event stream of the form:



[source,xml]

----

  

      

        Tom         

        Fennelly    

        M  

         21  

        IE  

      

      

        Maurice    

        Zeijen       

        M  

        27  

        NL  

      



----



== Defining fields



Fields are defined in the 'fields' attribute as a comma separated list of names and field lengths. The field lengths must be defined between the brackets after the field name (see the example above).



The field names must follow the same naming rules like XML element names:



* Names can contain letters, numbers, and other characters

* Names cannot start with a number or punctuation character

* Names cannot start with the letters xml (or XML, or Xml, etc...)

* Names cannot contain spaces



By setting the `+rootElementName+` and `+recordElementName+` attributes you can modify the and element names. The same naming rules apply for these names.



=== String manipulation functions



String manipulation functions can be defined per field. These functions are executed before that the data is converted into SAX events. The functions are defined after the field length definitions and are optionally separated with a question mark.



[source,xml]

----

  

  



    

      



----



The following functions are available:



* `+upper_case+`: Returns the upper case version of the string.

* `+lower_case+`: Returns the lower case version of the string.

* `+cap_first+`: Returns the string with the very first word of the string capitalized.

* `+uncap_first+`: Returns the string with the very first word of the string un-capitalized. The opposite to `+cap_first+`.

* `+capitalize+`: Returns the string with all words capitalized.

* `+trim+`: Returns the string without leading and trailing white-spaces.

* `+left_trim+`: Returns the string without leading white-spaces.

* `+right_trim+`: Returns the string without trailing white-spaces.



Functions can be chained via the point separator: `+trim.upper_case+`. It depends on the reader how the functions are defined per field. Please look at the individual chapters of the readers for that information.



=== Ignoring Fields



Characters ranges of a fixed-length record can be ignored by specifying the `+$ignore$[10]+` token in the fields configuration value. You must specify the number of characters that need be ignored, just as a normal field.



.smooks-config.xml

[source,xml]

----

  

  



      



----



== Binding Fixed-Length Records to Java



Smooks v1.2 has added support for making the binding of fixed-length records to Java Objects a very trivial task. You don't need to use the Javabean Cartridge directly (i.e. Smooks main Java binding functionality).



A Persons fixed-length record set such as:



....

Tom       Fennelly  M 21 IE  

Maurice  Zeijen     M 27 NL

....



Can be bound to a Person of (no getters/setters):



.Person.java

[source,java]

----

public class Person {  

    private String firstname;

    private String lastname;

    private String country;

    private String gender;

    private int age;  

}

----



Using a config of the form:



.smooks-config.xml

[source,xml]

----

  

  



      

          

          

      



----



To execute this configuration:



[source,java]

----

Smooks smooks = new Smooks(configStream);  

JavaSink sink = new JavaSink();



smooks.filterSource(new StreamSource(fixedLengthStream), sink);



List people = (List) sink.getBean("people");

----



Smooks also supports creation of maps from the fixed-length record set:



.smooks-config.xml

[source,xml]

----



    

        

    



----



The above configuration would produce a map of Person instances, keyed by the "firstname" value of each Person. It would be executed as follows:



[source,java]

----

Smooks smooks = new Smooks(configStream);  

JavaSink sink = new JavaSink();



smooks.filterSource(new StreamSource(fixedLengthStream), sink);



Map people = (Map) sink.getBean("people");



Person tom = people.get("Tom");  

Person mike = people.get("Maurice");

----



link:#virtual-object-models-maps--lists[Virtual Models] are also supported, so you can define the `+class+` attribute as a `+java.util.Map+` and have the fixed-length field values bound into Map instances, which are in turn added to a list or a map.



== Java API



Programmatically configuring the FixedLengthReader on a Smooks instance is trivial. A number of options are available.



=== Configuring Directly on the Smooks Instance



The following code configures a Smooks instance with a FixedLengthReader for reading a people record set (see above), binding the record set into a List of Person instances:



[source,java]

----

Smooks smooks = new Smooks();



smooks.setReaderConfig(new FixedLengthReaderConfigurator("firstname,lastname,gender,age,country")

                  .setBinding(new FixedLengthBinding("people", Person.class, CSVBindingType.LIST)));



JavaSink sink = new JavaSink();

smooks.filterSource(new ReaderSource(csvReader), sink);



List people = (List) sink.getBean("people");

----



Of course configuring the Java Binding is totally optional. The Smooks instance could instead (or in conjunction with) be programmatically configured with other visitor for carrying out other forms of processing on the fixed-length record set.



=== Fixed-Length List & Map Binders



If you're just interested in binding fixed-length records directly onto a List or Map of a Java type that reflects the data in your fixed-length records, then you can use the `+FixedLengthListBinder+` or `+FixedLengthMapBinder+` classes.



FixedLengthListBinder:



[source,java]

----

// Note: The binder instance should be cached and reused...

FixedLengthListBinder binder = new FixedLengthListBinder("firstname[10]?trim,lastname[10]?trim,gender[1],age[3]?trim,country[2]", Person.class);



List people = binder.bind(fixedLengthStream);

----



FixedLengthMapBinder:



[source,java]

----

// Note: The binder instance should be cached and reused...

FixedLengthMapBinder binder = new FixedLengthMapBinder("firstname[10]?trim,lastname[10]?trim,gender[1],age[3]?trim,country[2]", Person.class, "firstname");



Map people = binder.bind(fixedLengthStream);

----



If you need more control over the binding process, revert back to the lower level APIs:



* link:#configuring-directly-on-the-smooks-instance[Configuring Directly on the Smooks Instance]

* link:#java-binding[Java Binding]



== Maven Coordinates



.pom.xml

[source,xml]

----



    org.smooks.cartridges

    smooks-fixed-length-cartridge

    2.0.1

    

----



== XML Namespace



....

xmlns:fl="https://www.smooks.org/xsd/smooks/fixed-length-1.4.xsd"

....

// end::smooks-fixed-length-cartridge[]



== License



Smooks Fixed-Length Cartridge is open source and licensed under the terms of the Apache License Version 2.0, or the GNU Lesser General Public License version 3.0 or later. You may use Smooks Fixed-Length Cartridge according to either of these licenses as is most appropriate for your project.



`+SPDX-License-Identifier: Apache-2.0 OR LGPL-3.0-or-later+`