com.linkedin.multipart

Class MultiPartMIMEReader

java.lang.Object

com.linkedin.multipart.MultiPartMIMEReader

All Implemented Interfaces:

MultiPartMIMEDataSourceIterator

public class MultiPartMIMEReader
extends java.lang.Object
implements MultiPartMIMEDataSourceIterator

Zero copy, async streaming multipart mime reader based on the official RFC for multipart/mime. This class uses R2 streaming and a look-ahead buffer to allow clients to walk through the data of all parts using an async, callback based approach. Clients must first create a callback of type MultiPartMIMEReaderCallback to pass to registerReaderCallback(com.linkedin.multipart.MultiPartMIMEReaderCallback). This is the first step to using the MultiPartMIMEReader. Upon registration, at some time in the future, MultiPartMIMEReader will create MultiPartMIMEReader.SinglePartMIMEReaders which will be passed to MultiPartMIMEReaderCallback.onNewPart(com.linkedin.multipart.MultiPartMIMEReader.SinglePartMIMEReader). Clients will then have to create an instance of SinglePartMIMEReaderCallback to bind and commit to reading these parts. Note that NONE of the APIs in this class are thread safe. Furthermore it is to be noted that API calls must be event driven. For example, asking for more part data using MultiPartMIMEReader.SinglePartMIMEReader.requestPartData() can only be done either upon binding to the MultiPartMIMEReader.SinglePartMIMEReader or after receiving data on SinglePartMIMEReaderCallback.onPartDataAvailable(com.linkedin.data.ByteString). Therefore attempting to queue multiple reads, instead of waiting for callback invocations to drive forward, will result in runtime exceptions.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	MultiPartMIMEReader.SinglePartMIMEReader A reader to register with and walk through an individual multipart mime body.

Method Summary

Modifier and Type	Method and Description
void	abandonAllDataSources() Please do not use.
static MultiPartMIMEReader	createAndAcquireStream(com.linkedin.r2.message.stream.StreamRequest request) Create a MultiPartMIMEReader by acquiring the EntityStream from the provided StreamRequest.
static MultiPartMIMEReader	createAndAcquireStream(com.linkedin.r2.message.stream.StreamRequest request, MultiPartMIMEReaderCallback clientCallback) Create a MultiPartMIMEReader by acquiring the EntityStream from the provided StreamRequest.
static MultiPartMIMEReader	createAndAcquireStream(com.linkedin.r2.message.stream.StreamResponse response) Create a MultiPartMIMEReader by acquiring the EntityStream from the provided StreamResponse.
static MultiPartMIMEReader	createAndAcquireStream(com.linkedin.r2.message.stream.StreamResponse response, MultiPartMIMEReaderCallback clientCallback) Create a MultiPartMIMEReader by acquiring the EntityStream from the provided StreamResponse.
void	drainAllParts() Reads through and drains the current new part (if applicable) and additionally the whole stream.
boolean	haveAllPartsFinished() Indicates if all parts have been finished and completely read from this MultiPartMIMEReader.
void	registerDataSourceReaderCallback(MultiPartMIMEDataSourceIteratorCallback callback) Please do not use.
void	registerReaderCallback(MultiPartMIMEReaderCallback clientCallback) Register to read using this MultiPartMIMEReader.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

createAndAcquireStream

public static MultiPartMIMEReader createAndAcquireStream(com.linkedin.r2.message.stream.StreamRequest request,
                                                         MultiPartMIMEReaderCallback clientCallback)
                                                  throws MultiPartIllegalFormatException

Create a MultiPartMIMEReader by acquiring the EntityStream from the provided StreamRequest. Interacting with the MultiPartMIMEReader will happen through callbacks invoked on the provided MultiPartMIMEReaderCallback.

Parameters:

request - the request containing the EntityStream to read from.

clientCallback - the callback to invoke in order to drive the client forward for reading part data.

Returns:

the newly created MultiPartMIMEReader

Throws:

MultiPartIllegalFormatException - if the request is in any way not a valid multipart/mime request.

createAndAcquireStream

public static MultiPartMIMEReader createAndAcquireStream(com.linkedin.r2.message.stream.StreamResponse response,
                                                         MultiPartMIMEReaderCallback clientCallback)
                                                  throws MultiPartIllegalFormatException

Create a MultiPartMIMEReader by acquiring the EntityStream from the provided StreamResponse. Interacting with the MultiPartMIMEReader will happen through callbacks invoked on the provided MultiPartMIMEReaderCallback.

Parameters:

response - the response containing the EntityStream to read from.

clientCallback - the callback to invoke in order to drive the client forward for reading part data.

Returns:

the newly created MultiPartMIMEReader

Throws:

MultiPartIllegalFormatException - if the response is in any way not a valid multipart/mime response.

createAndAcquireStream

public static MultiPartMIMEReader createAndAcquireStream(com.linkedin.r2.message.stream.StreamRequest request)
                                                  throws MultiPartIllegalFormatException

Create a MultiPartMIMEReader by acquiring the EntityStream from the provided StreamRequest. Interacting with the MultiPartMIMEReader will require subsequent registration using a MultiPartMIMEReaderCallback.

Parameters:

request - the request containing the EntityStream to read from.

Returns:

the newly created MultiPartMIMEReader

Throws:

MultiPartIllegalFormatException - if the request is in any way not a valid multipart/mime request.

createAndAcquireStream

public static MultiPartMIMEReader createAndAcquireStream(com.linkedin.r2.message.stream.StreamResponse response)
                                                  throws MultiPartIllegalFormatException

Create a MultiPartMIMEReader by acquiring the EntityStream from the provided StreamResponse. Interacting with the MultiPartMIMEReader will require subsequent registration using a MultiPartMIMEReaderCallback.

Parameters:

response - the response containing the EntityStream to read from.

Returns:

the newly created MultiPartMIMEReader

Throws:

MultiPartIllegalFormatException - if the response is in any way not a valid multipart/mime response.

haveAllPartsFinished

public boolean haveAllPartsFinished()

Indicates if all parts have been finished and completely read from this MultiPartMIMEReader. If the last part is in the process of being read, this will return false.

Returns:

true if the reader is completely finished.

drainAllParts

public void drainAllParts()

Reads through and drains the current new part (if applicable) and additionally the whole stream. This API can be used in only the following scenarios: 1. Without registering a MultiPartMIMEReaderCallback. Draining will begin and since no callback is registered, there will be no notification when it is completed. 2. After registration using a MultiPartMIMEReaderCallback and after an invocation on MultiPartMIMEReaderCallback.onNewPart(com.linkedin.multipart.MultiPartMIMEReader.SinglePartMIMEReader). Draining will begin and when it is complete, a call will be made to MultiPartMIMEReaderCallback.onDrainComplete(). If this is called after registration and before an invocation on MultiPartMIMEReaderCallback.onNewPart(com.linkedin.multipart.MultiPartMIMEReader.SinglePartMIMEReader), then a StreamBusyException will be thrown. If this used after registration, then this can ONLY be called if there is no part being actively read, meaning that the current MultiPartMIMEReader.SinglePartMIMEReader has not been initialized with a SinglePartMIMEReaderCallback. If this is violated a StreamBusyException will be thrown. If the stream is finished, subsequent calls will throw MultiPartReaderFinishedException. Since this is async and request queueing is not allowed, repetitive calls will result in StreamBusyException.

registerReaderCallback

public void registerReaderCallback(MultiPartMIMEReaderCallback clientCallback)

Register to read using this MultiPartMIMEReader. Upon registration, at some point in the future, an invocation will be made on MultiPartMIMEReaderCallback.onNewPart(com.linkedin.multipart.MultiPartMIMEReader.SinglePartMIMEReader). This can ONLY be called if there is no part being actively read; meaning that the current MultiPartMIMEReader.SinglePartMIMEReader has not had a callback registered with it. Violation of this will throw a StreamBusyException. This can even be set if no parts in the stream have actually been consumed, i.e after the very first invocation of MultiPartMIMEReaderCallback.onNewPart(com.linkedin.multipart.MultiPartMIMEReader.SinglePartMIMEReader). If this MultiPartMIMEReader is finished, then attempts to register a callback will throw MultiPartReaderFinishedException.

Parameters:

clientCallback - the MultiPartMIMEReaderCallback which will be invoked upon to read this multipart mime body.

abandonAllDataSources

public void abandonAllDataSources()

Please do not use. This is for internal use only. Invoked when all the potential data sources that this MultiPartMIMEDataSourceIterator represents need to be aborted since they will not be given a chance to produce data.

Specified by:

abandonAllDataSources in interface MultiPartMIMEDataSourceIterator

registerDataSourceReaderCallback

public void registerDataSourceReaderCallback(MultiPartMIMEDataSourceIteratorCallback callback)

Please do not use. This is for internal use only. Invoked as the first step to walk through all potential data sources represented by this MultiPartMIMEDataSourceIterator.

Specified by:

registerDataSourceReaderCallback in interface MultiPartMIMEDataSourceIterator

Parameters:

callback - the callback that will be invoked as data sources become available for consumption.