Configure Custom Serializers | MuleSoft Documentation
# Configure Custom Serializers
By default, Mule runtime engine (Mule) uses ordinary Java serialization. However, you can configure `defaultObjectSerializer` in your Mule application to specify a different serialization mechanism, such as the Kryo serializer or any other custom serializer.
Using a custom serializer can improve functionality and performance when Mule executes any of the following processes:
  * Read from or write to a persistent object store
  * Read from or write to a persistent VM or JMS queue
  * Distribute an object through a Mule cluster
  * Read from or write to an object from a file


Customization does not affect the behavior of the Batch module, which always uses the Kryo serializer.
## Compatibility Between Serializers and Mule
If you are running Mule runtime engine (Enterprise Edition), you can configure the Kryo serializer to improve performance.
If you are using Mule Kernel (Community Edition), you can create a custom serializer using the Serialization API.
## Configure the Kryo Serializer
Mule provides an implementation of `ObjectSerializer` that relies on the Kryo framework. Using Kryo provides the following benefits:
  * Better performance Kryo is much faster than Java serialization.
  * Support for a wider range of Java types Kryo is not bound by most of the limitations that Java serialization imposes, such as requiring the implementation of the `Serializable` interface, having a default constructor, and so on.
  * Support for compression You can use either Deflate or GZip compression algorithms.


The Kryo namespace enables you to configure this serializer inside your Mule application, without defining a custom Spring bean. The following configuration example sets the default serializer to a Kryo-based one:
```
<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:kryo="http://www.mulesoft.org/schema/mule/kryo"
    xsi:schemaLocation="
    http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
    http://www.mulesoft.org/schema/mule/kryo http://www.mulesoft.org/schema/mule/kryo/current/mule-kryo.xsd">
  <kryo:serializer name="kryo" />
  <configuration defaultObjectSerializer-ref="kryo" />
</mule>
```

You can also include the `compressionMode` XML attribute to configure compression:
```
<kryo:serializer name="noCompression" compressionMode="NONE" /> <!-- NONE is the default value -->
<kryo:serializer name="deflate" compressionMode="DEFLATE" />
<kryo:serializer name="gzip" compressionMode="GZIP" />
```

## Create a Custom Serializer Using the Serialization API
The open-source Serialization API provides the `ObjectSerializer.java` interface, which enables you to serialize or deserialize objects into a byte array. See ObjectSerializer.java in GitHub.
The Serialization API has the following features:
  * Is thread-safe
  * Passes an OutputStream when serializing and streaming
  * Allows an InputStream as an input source


If you are going to serialize and deserialize in Mule, then you must define the `getInternalProtocol()` method. If you are going to use the serialized object in an external system, define that in the `getExternalProtocol()` method. A Serialization Protocol is the object used to serialize and deserialize.
## Configure a Custom Serializer
Configure the default `ObjectSerializer` for your Mule application using the Mule `<configuration>` tag:
```
<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:spring="http://www.springframework.org/schema/beans"
    xsi:schemaLocation="
    http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
    http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd">
 <spring:config name="Spring_Config" files="serializer.xml" />
 <configuration defaultObjectSerializer-ref="customSerializer" />
</mule>
```

Then, configure the bean in the `serializer.xml` file:
```
<?xml version="1.0" encoding="utf-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.3.xsd">
	<bean id="customSerializer" name="customSerializer"
		class="com.my.CustomSerializer">
		<!-- ... -->
	</bean>
</beans>
```

## Obtain a Configured ObjectSerializer
There are different ways to obtain an `ObjectSerializer` inside Java code. Generally, the recommended approach is through dependency injection. The following code example shows you how to get the currently configured `ObjectSerializer`:
```
public class MyClass {
  @Inject
  private ObjectSerializer objectSerializer;
}
```

If you want a specifically named serializer (whether it’s the default or not), you can access the serializer by name:
```
public class MyClass {
 @Inject
 @Named ("mySerializer")
 private ObjectSerializer objectSerializer;
}
```

## Performance Improvements with Kryo
Using Kryo provides particular performance improvements over ordinary Java serialization when you are using these components:
  * Persistent or clustered object stores
  * Persistent or distributed VM queues
  * JMS connector
Then, configure the bean in the `serializer.xml` file:
```
<?xml version="1.0" encoding="utf-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.3.xsd">
	<bean id="customSerializer" name="customSerializer"
		class="com.my.CustomSerializer">
		<!-- ... -->
	</bean>
</beans>
```

## Obtain a Configured ObjectSerializer
There are different ways to obtain an `ObjectSerializer` inside Java code. Generally, the recommended approach is through dependency injection. The following code example shows you how to get the currently configured `ObjectSerializer`:
```
public class MyClass {
  @Inject
  private ObjectSerializer objectSerializer;
}
```

If you want a specifically named serializer (whether it’s the default or not), you can access the serializer by name:
```
public class MyClass {
 @Inject
 @Named ("mySerializer")
 private ObjectSerializer objectSerializer;
}
```

## Performance Improvements with Kryo
Using Kryo provides particular performance improvements over ordinary Java serialization when you are using these components:
  * Persistent or clustered object stores
  * Persistent or distributed VM queues
  * JMS connector


The Kryo serializer without compression is significantly faster than the ordinary Java serializer in all cases. However, compression mode provides an improvement only in high availability (HA) cases.
For compression to be worthwhile, the amount of time the CPU spends compressing and decompressing has to be significantly lower than the amount of I/O time saved by reducing the payload size. Because network operations are typically slower than disk operations, and because HA clustering requires node replication (which translates to more traffic), compression is useful only in HA environments.
This is not a universal constant. You might be running Mule on machines with slower disks or higher I/O demands in which compression might be worthwhile in any case. Also, tests were performed using 1 MB payloads. If your data stream is larger, compression becomes more worthwhile.
## Considerations When Using Serialization
Ensure that you are aware of the following limitations and considerations when using serialization.
### Changing Serializers Requires a Clean Slate
Serializers are not interoperable nor interchangeable. That means that if you decide to change the serializer your application uses, ensure that all messages in VM and JMS queues have been consumed and that those queues are empty by the time the new serializer takes over.
The Kryo serializer won’t be able to read datagrams written by the Java serializer, and vice-versa. The same thing applies to persistent object stores; you cannot read with one serializer an entry generated with a different serializer.
### Shared VM Connectors Use the Domain’s Default Serializer
Domains provide a way to share resources between applications. For example, you can define a VM connector on a domain to allow inter-app communication through VM message queues.
However, serializers can be configured only at an application level; they cannot be configured at a domain level.
If applications A and B communicate with each other through a VM connector defined on a domain to which both belong, but A serializes using Java and B using Kryo, the serialization works because that particular message is not serialized with the application’s serializer but the one the VM connector uses (the default serializer at domain level). This is good for a "plug-and-play experience", but you won’t be able to realize a performance improvement by having that shared VM connector use Kryo.
### Java 17 Support
Starting with version 4.6, Mule runtime supports Java 17, which enforces JPMS. To achieve this capability, Mulesoft introduces several custom serializers that replace the default Kryo frameworks, because the default frameworks rely on mechanisms that break JPMS encapsulation. When migrating to Mule runtime 4.6 and Java 17, the Kryo serializer may not serialize an HTTP Connector certificate. This issue occurs if you are using the Kryo serializer together with an HTTP Connector that has a certificate among its attributes.
### Low Improvement For Local Persistent Object Stores
The local persistent object store has no performance advantage because of high contention on the object store implementation.
### Low Improvement For JMS Queues
The JSM API specifies that queues need to provide an instance of the `javax.jms.Message` class, the queues don’t work with raw payload objects. The broker client is responsible for serializing the message, not Mule. So, configuring Kryo has minimun impact in this scenario.
The only performance gain of using Kryo with JMS is that Mule serializes the MuleSession and uses it as a header in Base64 format. Serializing the MuleSession with Kryo can give you up to a 10% performance increase, but this is primarily attributable to the JMS broker instead of Mule.
### Problematic Types
Although Kryo is capable of serializing objects that don’t implement the `Serializable` interface, setting Kryo as the default serializer doesn’t mean that components such as the VM connector, ObjectSerializer, or cluster can handle objects that don’t implement such an interface. Although Kryo can work with those objects, the Java APIs for those components still expect instances of `Serializable` in their method signatures.
Ordinary Java serialization fails with an object that doesn’t implement the `Serializable` interface. However, if serialization contains another object which doesn’t implement the Serializable interface, Kryo is likely (but not guaranteed) to succeed. A typical case is a POJO containing an `org.apache.xerces.jaxp.datatype.XMLGregorianCalendarImpl,` which is in use in the NetSuite or Microsoft Dynamics CRM connectors.
## See Also
  *