io.humble.video.customio

Class HumbleIO

java.lang.Object

io.humble.video.customio.HumbleIO

All Implemented Interfaces:

IURLProtocolHandlerFactory

public class HumbleIO
extends Object
implements IURLProtocolHandlerFactory

Allows Humble Video to read from and write to many different types of Java I/O objects, plus custom IURLProtocolHandler objects.

Most of the time, Container hides this away from you, but in case you're interested, here's the underlying class doing the IO magic.

To use for reading (assuming an InputStream object called inputStream):

 Container container = Container.make();
 container.open(inputStream, null);
 

or for writing:

 Container container = Container.make();
 container.open(outputStream, null);
 

Really. That's it.

All streams that are mapped in this factory share the same name space, even if registered under different protocols. So, if "exampleone" and "exampletwo" were both registered as protocols for this factory, then "exampleone:filename" is the same as "exampletwo:filename" and will map to the same input and output streams. In reality, they are all mapped to the DEFAULT_PROTOCOL protocol.

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_PROTOCOL The default protocol string that this factory uses ( "humble").

Method Summary

Modifier and Type	Method and Description
static String	generateUniqueName(Object src) Generates a unique name suitable for using in the map methods for the URL parameter.
static String	generateUniqueName(Object src, String extension) Generates a unique name suitable for using in the map methods for the URL parameter.
static HumbleIO	getFactory() Get the singleton factory object for this class.
IURLProtocolHandler	getHandler(String protocol, String url, int flags) Called by FFMPEG in order to get a handler to use for a given file.
static String	map(ByteChannel channel) Maps a ByteChannel to a URL for use by Humble.
static String	map(DataInput input) Maps a DataInput object to a URL for use by Humble.
static String	map(DataOutput output) Maps a DataOutput object to a URL for use by Humble.
static String	map(InputStream in) Maps an InputStream to a URL for use by Humble.
static String	map(IURLProtocolHandler handler) Maps a IURLProtocolHandler to a url that Humble can open.
static String	map(OutputStream out) Maps an OutputStream to a URL for use by Humble.
static String	map(RandomAccessFile file) Maps a RandomAccessFile object to a URL for use by Humble.
static String	map(ReadableByteChannel channel) Maps a ReadableByteChannel to a URL for use by Humble.
static String	map(String url, ByteChannel channel) Maps a ByteChannel to a URL for use by Humble.
static String	map(String url, DataInput input) Maps a DataInput object to a URL for use by Humble.
static String	map(String url, DataInput in, DataOutput out, boolean unmapOnOpen, boolean closeOnClose) Maps a DataInput or DataOutput object to a URL for use by Humble.
static String	map(String url, DataOutput output) Maps a DataOutput object to a URL for use by Humble.
static String	map(String url, InputStream in) Maps an InputStream to a URL for use by Humble.
static String	map(String url, InputStream in, OutputStream out, boolean unmapOnOpen, boolean closeOnClose) Maps an InputStream or OutputStream to a URL for use by Humble.
static String	map(String url, IURLProtocolHandler handler) Maps a IURLProtocolHandler to a url that Humble can open.
static String	map(String url, IURLProtocolHandler handler, boolean unmapUrlOnOpen) Maps a IURLProtocolHandler to a url that Humble can open.
static String	map(String url, OutputStream out) Maps an OutputStream to a URL for use by Humble.
static String	map(String url, RandomAccessFile file) Maps a RandomAccessFile object to a URL for use by Humble.
static String	map(String url, ReadableByteChannel channel) Maps a ReadableByteChannel to a URL for use by Humble.
static String	map(String url, ReadableByteChannel in, WritableByteChannel out, boolean unmapOnOpen, boolean closeOnClose) Maps an ReadableByteChannel or WritableByteChannel to a URL for use by Humble.
static String	map(String url, WritableByteChannel channel) Maps a WritableByteChannel to a URL for use by Humble.
static String	map(WritableByteChannel channel) Maps a WritableByteChannel to a URL for use by Humble.
IURLProtocolHandler	mapIO(String url, IURLProtocolHandler handler, boolean unmapUrlOnOpen) Maps the given url or file name to the given IURLProtocolHandler or so that Humble calls to open the URL it will call back to the handler.
static IURLProtocolHandler	unmap(String url) Undoes a URL to InputStream or OutputStream mapping.
IURLProtocolHandler	unmapIO(String url) Unmaps a registration between a URL and the underlying i/o objects.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_PROTOCOL

public static final String DEFAULT_PROTOCOL

The default protocol string that this factory uses ( "humble").

See Also:

Constant Field Values

Method Detail

getFactory

public static HumbleIO getFactory()

Get the singleton factory object for this class.

Returns:

the factory

generateUniqueName

public static String generateUniqueName(Object src)

Generates a unique name suitable for using in the map methods for the URL parameter.

Parameters:

src - The object you want to generate a unique name for, or null if you don't have one.

Returns:

A unique name (will be unique across time and space).

generateUniqueName

public static String generateUniqueName(Object src,
                                        String extension)

Generates a unique name suitable for using in the map methods for the URL parameter.

Parameters:

src - The object you want to generate a unique name for, or null if you don't have one.

extension - an option extension to append to the generated URL.

Returns:

A unique name (will be unique across time and space).

map

public static String map(IURLProtocolHandler handler)

Maps a IURLProtocolHandler to a url that Humble can open. unmap(String) will be called automatically after this URL is opened.

Parameters:

handler - the handler

Returns:

a string that is suitable for passing to Container's open methods.

map

public static String map(String url,
                         IURLProtocolHandler handler)

Maps a IURLProtocolHandler to a url that Humble can open. unmap(String) will be called automatically after this URL is opened.

Parameters:

url - the unique string to use for the mapping.

handler - the handler

Returns:

a string that is suitable for passing to Container's open methods.

map

public static String map(DataInput input)

Maps a DataInput object to a URL for use by Humble.

Parameters:

input - the DataInput

Returns:

a string that can be passed to Container's open methods.

map

public static String map(String url,
                         DataInput input)

Maps a DataInput object to a URL for use by Humble.

Parameters:

url - the URL to use.

input - the DataInput

Returns:

a string that can be passed to Container's open methods.

map

public static String map(DataOutput output)

Maps a DataOutput object to a URL for use by Humble.

Parameters:

output - the DataOutput

Returns:

a string that can be passed to Container's open methods.

map

public static String map(String url,
                         DataOutput output)

Maps a DataOutput object to a URL for use by Humble.

Parameters:

url - the URL to use.

output - the DataOutput

Returns:

a string that can be passed to Container's open methods.

map

public static String map(RandomAccessFile file)

Maps a RandomAccessFile object to a URL for use by Humble.

Parameters:

file - the RandomAccessFile

Returns:

a string that can be passed to Container's open methods.

map

public static String map(String url,
                         RandomAccessFile file)

Maps a RandomAccessFile object to a URL for use by Humble.

Parameters:

url - the URL to use.

file - the RandomAccessFile

Returns:

a string that can be passed to Container's open methods.

map

public static String map(ReadableByteChannel channel)

Maps a ReadableByteChannel to a URL for use by Humble.

Parameters:

channel - the ReadableByteChannel

Returns:

a string that can be passed to Container's open methods.

map

public static String map(String url,
                         ReadableByteChannel channel)

Maps a ReadableByteChannel to a URL for use by Humble.

Parameters:

url - the URL to use.

channel - the ReadableByteChannel

Returns:

a string that can be passed to Container's open methods.

map

public static String map(WritableByteChannel channel)

Maps a WritableByteChannel to a URL for use by Humble.

Parameters:

channel - the WritableByteChannel

Returns:

a string that can be passed to Container's open methods.

map

public static String map(String url,
                         WritableByteChannel channel)

Maps a WritableByteChannel to a URL for use by Humble.

Parameters:

url - the URL to use.

channel - the WritableByteChannel

Returns:

a string that can be passed to Container's open methods.

map

public static String map(ByteChannel channel)

Maps a ByteChannel to a URL for use by Humble.

Parameters:

channel - the ByteChannel

Returns:

a string that can be passed to Container's open methods.

map

public static String map(String url,
                         ByteChannel channel)

Maps a ByteChannel to a URL for use by Humble.

Parameters:

url - the URL to use.

channel - the ByteChannel

Returns:

a string that can be passed to Container's open methods.

map

public static String map(InputStream in)

Maps an InputStream to a URL for use by Humble.

Parameters:

in - the stream

Returns:

Returns a URL that can be passed to Humble's Container's open method, and will result in IO being performed on the passed in streams.

map

public static String map(String url,
                         InputStream in)

Maps an InputStream to a URL for use by Humble.

Parameters:

url - the URL to use.

in - the stream

Returns:

Returns a URL that can be passed to Humble's Container's open method, and will result in IO being performed on the passed in streams.

map

public static String map(OutputStream out)

Maps an OutputStream to a URL for use by Humble.

Parameters:

out - the stream

Returns:

Returns a URL that can be passed to Humble's Container's open method, and will result in IO being performed on the passed in streams.

map

public static String map(String url,
                         OutputStream out)

Maps an OutputStream to a URL for use by Humble.

Parameters:

url - the URL to use.

out - the stream

Returns:

Returns a URL that can be passed to Humble's Container's open method, and will result in IO being performed on the passed in streams.

map

public static String map(String url,
                         DataInput in,
                         DataOutput out,
                         boolean unmapOnOpen,
                         boolean closeOnClose)

Maps a DataInput or DataOutput object to a URL for use by Humble.

Parameters:

url - the url

in - the input to use

out - the output to use

unmapOnOpen - should we remove the mapping as soon as the resulting handler is opened?

closeOnClose - should we call Closeable.close() on the underlying input or output objects when IURLProtocolHandler.close() is called (if supported by the underlying object)?

Returns:

Returns a URL that can be passed to Humble's Container's open method, and will result in IO being performed on the passed in streams.

map

public static String map(String url,
                         ReadableByteChannel in,
                         WritableByteChannel out,
                         boolean unmapOnOpen,
                         boolean closeOnClose)

Maps an ReadableByteChannel or WritableByteChannel to a URL for use by Humble.

Parameters:

url - the url

in - the input to use

out - the output to use

unmapOnOpen - should we remove the mapping as soon as the resulting handler is opened?

closeOnClose - should we call Closeable.close() on the underlying input or output objects when IURLProtocolHandler.close() is called (if supported by the underlying object)?

Returns:

Returns a URL that can be passed to Humble's Container's open method, and will result in IO being performed on the passed in streams.

map

public static String map(String url,
                         InputStream in,
                         OutputStream out,
                         boolean unmapOnOpen,
                         boolean closeOnClose)

Maps an InputStream or OutputStream to a URL for use by Humble.

Parameters:

url - the url

in - the input to use

out - the output to use

unmapOnOpen - should we remove the mapping as soon as the resulting handler is opened?

closeOnClose - should we call Closeable.close() on the underlying input or output objects when IURLProtocolHandler.close() is called?

Returns:

Returns a URL that can be passed to Humble's Container's open method, and will result in IO being performed on the passed in streams.

map

public static String map(String url,
                         IURLProtocolHandler handler,
                         boolean unmapUrlOnOpen)

Maps a IURLProtocolHandler to a url that Humble can open.

Parameters:

url - the unique string to use for the mapping.

handler - the handler

unmapUrlOnOpen - if true, when Humble opens the IURLProtocolHandler, unmap(String) will be called automatically.

Returns:

a string that is suitable for passing to Container's open methods.

unmap

public static IURLProtocolHandler unmap(String url)

Undoes a URL to InputStream or OutputStream mapping. Forwards to getFactory().unmapIO(String)

mapIO

public IURLProtocolHandler mapIO(String url,
                                 IURLProtocolHandler handler,
                                 boolean unmapUrlOnOpen)

Maps the given url or file name to the given IURLProtocolHandler or so that Humble calls to open the URL it will call back to the handler.

If you set unmapOnOpen to false, or you never actually open this mapping, then you must ensure that you call unmapIO(String) at some point in time to remove the mapping, or we will hold onto references to the handler you passed in.

Parameters:

url - A file or URL. If a URL, the protocol will be stripped off and replaced with DEFAULT_PROTOCOL when registering.

handler - An IURLProtocolHandler for the url

unmapUrlOnOpen - If true, the handler will unmap itself after an Container opens the registered URL. If true, you do not need to call unmapIO(String) for this url.

Returns:

The previous handler for this url, or null if none.

Throws:

IllegalArgumentException - if url is null or zero length

IllegalArgumentException - if handler is null

unmapIO

public IURLProtocolHandler unmapIO(String url)

Unmaps a registration between a URL and the underlying i/o objects.

If URL contains a protocol it is ignored when trying to find the matching IO stream.

Parameters:

url - The stream name to unmap

Returns:

the IURLProtocolHandler that had been registered for that url, or null if none.

getHandler

public IURLProtocolHandler getHandler(String protocol,
                                      String url,
                                      int flags)

Called by FFMPEG in order to get a handler to use for a given file.

Specified by:

getHandler in interface IURLProtocolHandlerFactory

Parameters:

protocol - The protocol without a ':'. For example, "file", "http", or "yourcustomprotocol"

url - The URL that FFMPEG is trying to open.

flags - The flags that FFMPEG will pass to IURLProtocolHandler.open(String, int)

Returns:

A IURLProtocolHandler to use, or null. If null, a file not found error will be passed back to FFMPEG.