= ASN.1 File DataFormat
:doctitle: ASN.1 File
:shortname: asn1
:artifactid: camel-asn1
:description: Encode and decode data structures using Abstract Syntax Notation One (ASN.1).
:since: 2.20
:supportlevel: Stable
:tabs-sync-option:
//Manually maintained attributes
:camel-spring-boot-name: asn1

*Since Camel {since}*

The https://www.itu.int/en/ITU-T/asn1/Pages/introduction.aspx[ASN.1 Data Format] is a Camel Framework's data format implementation based on Bouncy Castle's bcprov-jdk18on 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.
With the help of Camel's routing engine and data transformations, you can then play with POJO(s) and apply customized formatting and call other Camel Components to convert and send messages to upstream systems.

== ASN.1 Data Format Options

// dataformat options: START
include::partial$dataformat-options.adoc[]
// dataformat options: END

== 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 a 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-jdk18on 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(bodyAs(Iterator.class)).streaming()
        .to("mock:unmarshal");
-----------------------------------------------------------------------

In the last example, we unmarshalled a 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 the https://www.beanit.com/asn1/[JASN.1 Project Page] 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(bodyAs(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 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>
----------------------------------------------------------


include::spring-boot:partial$starter.adoc[]
