[[asn1-dataformat]]
= ASN.1 File DataFormat
:page-source: components/camel-asn1/src/main/docs/asn1-dataformat.adoc

*Available as of Camel version 2.20*

The ASN.1 Data Format Data Format [Intoduction to ASN.1](https://www.itu.int/en/ITU-T/asn1/Pages/introduction.aspx) is a Camel Frameworks's data format implementation based on Bouncy Castle's bcprov-jdk15on library and jASN.1's java compiler for the formal notation used for describing data transmitted by telecommunications protocols, regardless of language implementation and physical representation of these data, whatever the application, whether complex or very simple. Messages can be unmarshalled (conversion to simple Java POJO(s)) to plain Java objects. By the help of Camel's routing engine and data transformations you can then play with POJO(s) and apply customised formatting and call other Camel Component's to convert and send messages to upstream systems.

== ASN.1 Data Format Options

// dataformat options: START
The ASN.1 File dataformat supports 3 options, which are listed below.


[width="100%",cols="2s,1m,1m,6",options="header"]
|===
| Name | Default | Java Type | Description
| usingIterator | false | Boolean | If the asn1 file has more then one entry, the setting this option to true, allows to work with the splitter EIP, to split the data using an iterator in a streaming mode.
| clazzName |  | String | Name of class to use when unmarshalling
| contentTypeHeader | false | Boolean | Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc.
|===
// dataformat options: END
// spring-boot-auto-configure options: START
== Spring Boot Auto-Configuration

When using Spring Boot make sure to use the following Maven dependency to have support for auto configuration:

[source,xml]
----
<dependency>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-asn1-starter</artifactId>
  <version>x.x.x</version>
  <!-- use the same version as your Camel core version -->
</dependency>
----


The component supports 4 options, which are listed below.


[width="100%",cols="2,5,^1,2",options="header"]
|===
| Name | Description | Default | Type
| *camel.dataformat.asn1.clazz-name* | Name of class to use when unmarshalling |  | String
| *camel.dataformat.asn1.content-type-header* | Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc. | false | Boolean
| *camel.dataformat.asn1.enabled* | Whether to enable auto configuration of the asn1 data format. This is enabled by default. |  | Boolean
| *camel.dataformat.asn1.using-iterator* | If the asn1 file has more then one entry, the setting this option to true, allows to work with the splitter EIP, to split the data using an iterator in a streaming mode. | false | Boolean
|===
// spring-boot-auto-configure options: END
ND

== Unmarshal

There are 3 different ways to unmarshal ASN.1 structured messages. (Usually binary files)

In this first example we unmarshal BER file payload to OutputStream and send it to mock endpoint.

[source,java]
-----------------------------------------------------------------------
from("direct:unmarshal").unmarshal(asn1).to("mock:unmarshal");
-----------------------------------------------------------------------

In the second example we unmarshal BER file payload to byte array using Split EIP. The reason for applying Split EIP is that usually each BER file or (ASN.1 structured file) contains multiple records to process and Split EIP helps us to get each record in a file as byte arrays which is actually ASN1Primitive's instance (by the use of Bouncy Castle's ASN.1 support in bcprov-jdk15on library)
Byte arrays then may be converted to ASN1Primitive by the help of public static method in (ASN1Primitive.fromByteArray)
In such example, note that you need to set `usingIterator=true`

[source,java]
-----------------------------------------------------------------------
from("direct:unmarshal").unmarshal(asn1).split(body(Iterator.class)).streaming().to("mock:unmarshal");
-----------------------------------------------------------------------

In the last example we unmarshal BER file payload to plain old Java Objects using Split EIP. The reason for applying Split EIP is already mentioned in the previous example. Please note and keep in mind that reason. In such example we also need to set the fully qualified name of the class or <YourObject>.class reference through data format.
The important thing to note here is that your object should have been generated by jasn1 compiler which is a nice tool to generate java object representations of your ASN.1 structure. For the reference usage of jasn1 compiler see [JASN.1 Project Page](https://www.beanit.com/asn1/) and please also see how the compiler is invoked with the help of maven's exec plugin.
For example, in this data format's unit tests an example ASN.1 structure(TestSMSBerCdr.asn1) is added in `src/test/resources/asn1_structure`. jasn1 compiler is invoked and java object's representations are generated in `$\{basedir\}/target/generated/src/test/java`
The nice thing about this example, you will get POJO instance at the mock endpoint or at whatever your endpoint is.    

[source,java]
-----------------------------------------------------------------------
from("direct:unmarshaldsl")
         .unmarshal()
         .asn1("org.apache.camel.dataformat.asn1.model.testsmscbercdr.SmsCdr")
         .split(body(Iterator.class)).streaming()
.to("mock:unmarshaldsl");
-----------------------------------------------------------------------

== Dependencies

To use ASN.1 data format in your camel routes you need to add a dependency on
*camel-asn1* which implements this data format.

If you use Maven you can just add the following to your `pom.xml`,
substituting the version number for the latest & greatest release (see
the download page for the latest versions).

[source,xml]
----------------------------------------------------------
<dependency>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-asn1</artifactId>
  <version>x.x.x</version>
  <!-- use the same version as your Camel core version -->
</dependency>
----------------------------------------------------------