org.apache.flume.serialization

Interface EventSerializer

All Known Subinterfaces:

EventSerDe

All Known Implementing Classes:

AbstractAvroEventSerializer, AvroEventSerializer, BodyTextEventSerializer, FlumeEventAvroEventSerializer, HeaderAndBodyTextEventSerializer

@InterfaceAudience.Public
 @InterfaceStability.Stable
public interface EventSerializer

This interface provides callbacks for important serialization-related events. This allows generic implementations of serializers to be plugged in, allowing implementations of this interface to do arbitrary header and message formatting, as well as file and message framing.

The following general semantics should be used by drivers that call this interface:

 // open file (for example... or otherwise create some new stream)
 OutputStream out = new FileOutputStream(file); // open for create

 // build serializer using builder interface
 EventSerializer serializer = builder.build(ctx, out);

 // hook to write header (since in this case we opened the file for create)
 serializer.afterCreate();

 // write one or more events
 serializer.write(event1);
 serializer.write(event2);
 serializer.write(event3);

 // periodically flush any internal buffers from EventSerializer.write()
 serializer.flush();

 // The driver responsible for specifying and implementing its durability
 // semantics (if any) for flushing or syncing the underlying stream.
 out.flush();

 // when closing the file...

 // make sure we got all buffered events flushed from the serializer
 serializer.flush();

 // write trailer before closing file
 serializer.beforeClose();

 // Driver is responsible for flushing the underlying stream, if needed,
 // before closing it.
 out.flush();
 out.close();
 

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	EventSerializer.Builder Knows how to construct this event serializer. Note: Implementations MUST provide a public a no-arg constructor.

Field Summary

Fields

Modifier and Type	Field and Description
static String	CTX_PREFIX Context prefix

Method Summary

Modifier and Type	Method and Description
void	afterCreate() Hook to write a header after file is opened for the first time.
void	afterReopen() Hook to handle any framing needed when file is re-opened (for write). Could have been named afterOpenForAppend().
void	beforeClose() Hook to write a trailer before the stream is closed.
void	flush() Hook to flush any internal write buffers to the underlying stream.
boolean	supportsReopen() Specify whether this output format supports reopening files for append.
void	write(Event event) Serialize and write the given event.

Field Detail

CTX_PREFIX

static final String CTX_PREFIX

Context prefix

See Also:

Constant Field Values

Method Detail

afterCreate

void afterCreate()
          throws IOException

Hook to write a header after file is opened for the first time.

Throws:

IOException

afterReopen

void afterReopen()
          throws IOException

Hook to handle any framing needed when file is re-opened (for write).
Could have been named afterOpenForAppend().

Throws:

IOException

write

void write(Event event)
    throws IOException

Serialize and write the given event.

Parameters:

event - Event to write to the underlying stream.

Throws:

IOException

flush

void flush()
    throws IOException

Hook to flush any internal write buffers to the underlying stream. It is NOT necessary for an implementation to then call flush() / sync() on the underlying stream itself, since those semantics would be provided by the driver that calls this API.

Throws:

IOException

beforeClose

void beforeClose()
          throws IOException

Hook to write a trailer before the stream is closed. Implementations must not buffer data in this call since EventSerializer.flush() is not guaranteed to be called after beforeClose().

Throws:

IOException

supportsReopen

boolean supportsReopen()

Specify whether this output format supports reopening files for append. For example, this method should return false if beforeClose() writes a trailer that "finalizes" the file (this type of behavior is file format-specific).
Could have been named supportsAppend().