GridOptimizedMarshaller (gridgain-core 6.1.9 API)

java.lang.Object
- org.gridgain.grid.marshaller.GridAbstractMarshaller
- - org.gridgain.grid.marshaller.optimized.GridOptimizedMarshaller

All Implemented Interfaces:: GridMarshaller

public class GridOptimizedMarshaller
extends GridAbstractMarshaller

Optimized implementation of GridMarshaller. Unlike GridJdkMarshaller, which is based on standard ObjectOutputStream, this marshaller does not enforce that all serialized objects implement Serializable interface. It is also about 20 times faster as it removes lots of serialization overhead that exists in default JDK implementation.

GridOptimizedMarshaller is tested only on Java HotSpot VM on other VMs it could yield unexpected results. It is the default marshaller on Java HotSpot VMs and will be used if no other marshaller was explicitly configured.

This marshaller has no mandatory configuration parameters.

 GridOptimizedMarshaller marshaller = new GridOptimizedMarshaller();

 // Enforce Serializable interface.
 marshaller.setRequireSerializable(true);

 GridConfiguration cfg = new GridConfiguration();

 // Override marshaller.
 cfg.setMarshaller(marshaller);

 // Starts grid.
 G.start(cfg);

GridOptimizedMarshaller can be configured from Spring XML configuration file:

 <bean id="grid.custom.cfg" class="org.gridgain.grid.GridConfiguration" singleton="true">
     ...
     <property name="marshaller">
         <bean class="org.gridgain.grid.marshaller.optimized.GridOptimizedMarshaller">
             <property name="requireSerializable">true</property>
         </bean>
     </property>
     ...
 </bean>

For information about Spring framework visit www.springframework.org

GridMarshaller can be injected in users task, job or SPI as following:

 public class MyGridJob implements GridComputeJob {
     ...
     @GridMarshallerResource
     private GridMarshaller marshaller;
     ...
 }

 public class MyGridJob implements GridComputeJob {
     ...
     private GridMarshaller marshaller;
     ...
     @GridMarshallerResource
     public void setMarshaller(GridMarshaller marshaller) {
         this.marshaller = marshaller;
     }
     ...
 }

Field Summary
- Fields inherited from class org.gridgain.grid.marshaller.GridAbstractMarshaller
  DFLT_BUFFER_SIZE

Constructor Summary

Constructors
Constructor and Description
`GridOptimizedMarshaller()` Initializes marshaller not to enforce `Serializable` interface.
`GridOptimizedMarshaller(boolean requireSer)` Initializes marshaller with given serialization flag.
`GridOptimizedMarshaller(boolean requireSer, List<String> clsNames, String clsNamesPath, int poolSize)` Initializes marshaller with given serialization flag.

Method Summary

Methods
Modifier and Type	Method and Description
`static boolean`	`available()` Checks whether `GridOptimizedMarshaller` is able to work on the current JVM.
`static void`	`clearCache()` Clears internal caches and frees memory.
`boolean`	`isRequireSerializable()`
`byte[]`	`marshal(Object obj)` Marshals object to byte array.
`void`	`marshal(Object obj, OutputStream out)` Marshals object to the output stream.
`static void`	`onUndeploy(ClassLoader ldr)` Undeployment callback invoked when class loader is being undeployed.
`void`	`setClassNames(List<String> clsNames)` Adds provided class names for marshalling optimization.
`void`	`setClassNamesPath(String path)` Specifies a name of the file which lists all class names to be optimized.
`void`	`setPoolSize(int poolSize)` Specifies size of cached object streams used by marshaller.
`void`	`setRequireSerializable(boolean requireSer)` Sets flag to enforce `Serializable` interface or not.
`<T> T`	`unmarshal(byte[] arr, ClassLoader clsLdr)` Unmarshals object from byte array using given class loader.
`<T> T`	`unmarshal(InputStream in, ClassLoader clsLdr)` Unmarshals object from the output stream using given class loader.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - GridOptimizedMarshaller
```
public GridOptimizedMarshaller()
```
    Initializes marshaller not to enforce Serializable interface.
    
    Throws:
    
    GridRuntimeException - If this marshaller is not supported on the current JVM.
  - GridOptimizedMarshaller
```
public GridOptimizedMarshaller(boolean requireSer)
```
    Initializes marshaller with given serialization flag. If true, then objects will be required to implement Serializable in order to be serialize.
    
    Parameters:
    requireSer - Flag to enforce Serializable interface or not. If true, then objects will be required to implement Serializable in order to be marshalled, if false, then such requirement will be relaxed.
    
    Throws:
    
    GridRuntimeException - If this marshaller is not supported on the current JVM.
  - GridOptimizedMarshaller
```
public GridOptimizedMarshaller(boolean requireSer,
                       @Nullable
                       List<String> clsNames,
                       @Nullable
                       String clsNamesPath,
                       int poolSize)
                        throws GridException
```
    Initializes marshaller with given serialization flag. If true, then objects will be required to implement Serializable in order to be serialize.
    
    Parameters:
    requireSer - Flag to enforce Serializable interface or not. If true, then objects will be required to implement Serializable in order to be marshalled, if false, then such requirement will be relaxed.
    clsNames - User preregistered class names.
    clsNamesPath - Path to a file with user preregistered class names.
    poolSize - Object streams pool size.
    
    Throws:
    
    GridException - If an I/O error occurs while writing stream header.
    
    GridRuntimeException - If this marshaller is not supported on the current JVM.
- Method Detail
  - setClassNames
```
public void setClassNames(@Nullable
                 List<String> clsNames)
```
    Adds provided class names for marshalling optimization.
    NOTE: these collections of classes must be identical on all nodes and in the same order.
    
    Parameters:
    clsNames - User preregistered class names to add.
  - setClassNamesPath
```
public void setClassNamesPath(@Nullable
                     String path)
                       throws GridException
```
    Specifies a name of the file which lists all class names to be optimized. The file path can either be absolute path, relative to GRIDGAIN_HOME, or specify a resource file on the class path.
    The format of the file is class name per line, like this:
```
 ...
 com.example.Class1
 com.example.Class2
 ...
 
```
    NOTE: this class list must be identical on all nodes and in the same order.
    Parameters:
    path - Path to a file with user preregistered class names.
    
    Throws:
    
    GridException - If an error occurs while writing stream header.
  - setPoolSize
```
public void setPoolSize(int poolSize)
```
    Specifies size of cached object streams used by marshaller. Object streams are cached for performance reason to avoid costly recreation for every serialization routine. If 0 (default), pool is not used and each thread has its own cached object stream which it keeps reusing.
    Since each stream has an internal buffer, creating a stream for each thread can lead to high memory consumption if many large messages are marshalled or unmarshalled concurrently. Consider using pool in this case. This will limit number of streams that can be created and, therefore, decrease memory consumption.
    NOTE: Using streams pool can decrease performance since streams will be shared between different threads which will lead to more frequent context switching.
    
    Parameters:
    poolSize - Streams pool size. If 0, pool is not used.
  - isRequireSerializable
```
public boolean isRequireSerializable()
```
    Returns:
    Whether to enforce Serializable interface.
  - setRequireSerializable
```
public void setRequireSerializable(boolean requireSer)
```
    Sets flag to enforce Serializable interface or not.
    
    Parameters:
    requireSer - Flag to enforce Serializable interface or not. If true, then objects will be required to implement Serializable in order to be marshalled, if false, then such requirement will be relaxed.
  - marshal
```
public void marshal(@Nullable
           Object obj,
           OutputStream out)
             throws GridException
```
    Marshals object to the output stream. This method should not close given output stream.
    
    Parameters:
    obj - Object to marshal.
    out - Output stream to marshal into.
    
    Throws:
    
    GridException - If marshalling failed.
  - marshal
```
public byte[] marshal(@Nullable
             Object obj)
               throws GridException
```
    Marshals object to byte array.
    
    Specified by:
    
    marshal in interface GridMarshaller
    
    Overrides:
    
    marshal in class GridAbstractMarshaller
    
    Parameters:
    obj - Object to marshal.
    
    Returns:
    Byte array.
    
    Throws:
    
    GridException - If marshalling failed.
  - unmarshal
```
public <T> T unmarshal(InputStream in,
              @Nullable
              ClassLoader clsLdr)
            throws GridException
```
    Unmarshals object from the output stream using given class loader. This method should not close given input stream.
    
    Type Parameters:
    T - Type of unmarshalled object.
    Parameters:
    in - Input stream.
    clsLdr - Class loader to use.
    
    Returns:
    Unmarshalled object.
    
    Throws:
    
    GridException - If unmarshalling failed.
  - unmarshal
```
public <T> T unmarshal(byte[] arr,
              @Nullable
              ClassLoader clsLdr)
            throws GridException
```
    Unmarshals object from byte array using given class loader.
    
    Specified by:
    
    unmarshal in interface GridMarshaller
    
    Overrides:
    
    unmarshal in class GridAbstractMarshaller
    
    Type Parameters:
    T - Type of unmarshalled object.
    Parameters:
    arr - Byte array.
    clsLdr - Class loader to use.
    
    Returns:
    Unmarshalled object.
    
    Throws:
    
    GridException - If unmarshalling failed.
  - available
```
public static boolean available()
```
    Checks whether GridOptimizedMarshaller is able to work on the current JVM.
    As long as GridOptimizedMarshaller uses JVM-private API, which is not guaranteed to be available on all JVM, this method should be called to ensure marshaller could work properly.
    Result of this method is automatically checked in constructor.
    
    Returns:
    true if GridOptimizedMarshaller can work on the current JVM or false if it can't.
  - onUndeploy
```
public static void onUndeploy(ClassLoader ldr)
```
    Undeployment callback invoked when class loader is being undeployed.
    
    Parameters:
    ldr - Class loader being undeployed.
  - clearCache
```
public static void clearCache()
```
    Clears internal caches and frees memory. Usually called on system stop.

Class GridOptimizedMarshaller

Configuration

Mandatory

Java Example

Spring Example

Injection Example

Field Summary

Fields inherited from class org.gridgain.grid.marshaller.GridAbstractMarshaller

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

GridOptimizedMarshaller

GridOptimizedMarshaller

GridOptimizedMarshaller

Method Detail

setClassNames

setClassNamesPath

setPoolSize

isRequireSerializable

setRequireSerializable

marshal

marshal

unmarshal

unmarshal

available

onUndeploy

clearCache