Module com.aoapps.encoding

Package com.aoapps.encoding

Class MediaEncoder

java.lang.Object

com.aoapps.encoding.MediaEncoder

All Implemented Interfaces:

ValidMediaFilter, ValidMediaInput, ValidMediaOutput, Encoder

Direct Known Subclasses:

BufferedEncoder, JavaScriptInXhtmlAttributeEncoder, JavaScriptInXhtmlEncoder, StyleInXhtmlAttributeEncoder, StyleInXhtmlEncoder, TextInJavaScriptEncoder, TextInMysqlEncoder, TextInPsqlEncoder, TextInShEncoder, TextInStyleEncoder, TextInXhtmlAttributeEncoder, TextInXhtmlEncoder, ValidateOnlyEncoder

@ThreadSafe
public abstract class MediaEncoder
extends Object
implements Encoder, ValidMediaFilter

Encodes media to allow it to be contained in a different type of media. For example, one may have plaintext inside of HTML, or arbitrary text inside a JavaScript String inside an onclick attribute of an area tag in a XHTML document. All necessary encoding is automatically performed.

Each encoder both validates its input characters and produces valid output characters.

Author:

AO Industries, Inc.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	MediaEncoder()

Method Summary

Modifier and Type	Method	Description
abstract MediaEncoder	append(char c, Appendable out)
abstract MediaEncoder	append(CharSequence csq, int start, int end, Appendable out)
abstract MediaEncoder	append(CharSequence csq, Appendable out)
static MediaEncoder	getInstance(EncodingContext encodingContext, MediaType contentType, MediaType containerType)	Gets the media encoder for the requested types or null if no encoding is necessary.
abstract void	write(char[] cbuf, int off, int len, Writer out)
abstract void	write(char[] cbuf, Writer out)
abstract void	write(int c, Writer out)
abstract void	write(String str, int off, int len, Writer out)
abstract void	write(String str, Writer out)
void	writePrefixTo(Appendable out)
final void	writeSuffixTo(Appendable out)	Deprecated. Please use writeSuffixTo(java.lang.Appendable, boolean) while specifying desired trim.
void	writeSuffixTo(Appendable out, boolean trim)

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.aoapps.lang.io.Encoder

isBuffered

Methods inherited from interface com.aoapps.encoding.ValidMediaInput

canSkipValidation, getValidMediaInputType, isValidatingMediaInputType

Methods inherited from interface com.aoapps.encoding.ValidMediaOutput

getValidMediaOutputType

Constructor Details

MediaEncoder

protected MediaEncoder()

Method Details

getInstance

public static MediaEncoder getInstance(EncodingContext encodingContext,
 MediaType contentType,
 MediaType containerType)
                                throws UnsupportedEncodingException

Gets the media encoder for the requested types or null if no encoding is necessary. When an encoder is returned it is also a validator for the contentType and produces valid output for the containerType.

An encoder is not needed when no prefix or suffix is needed, all valid contentType characters are also valid in containerType, and with the same representation. Furthermore, there must be some meaningful relationship between contentType and containerType - simply having compatible characters alone is insufficient.

When no encoder is returned, it is necessary to use a separate validator if character validation is required.

Media encoder implementations are extremely light weight. Although they can be reused after calling writeSuffixTo(java.lang.Appendable, boolean), there is likely no benefit in caching or reusing instances. The only possible exception would be any BufferedEncoder, which currently is only the encoders for MediaType.URL; however, since URLs are generally fairly short, the reuse of underlying buffers would be of marginal benefit.

Please note that most types can be encoded both to and from MediaType.TEXT. Thus, when a specialized encoder is not available (as indicated by throwing UnsupportedEncodingException), it may be possible to use an intermediate TEXT to connect between types, such as CSS -> TEXT -> XHTML will just display the raw CSS directly.

No automatic intermediate TEXT conversion is done, because the addition of new encoders could suddenly change the semantics.

Note: The supported encoders precisely matches the specialized subclasses of MediaWriter that implement per-type interfaces.

Parameters:

encodingContext - Required encoding context

Returns:

the encoder or null if no encoding is necessary. If an encoder is still needed for API requirements (such as required for MediaWriter), can use ValidateOnlyEncoder.

Throws:

UnsupportedEncodingException - when unable to encode the content into the container either because it is impossible or not yet implemented.

writePrefixTo

public void writePrefixTo(Appendable out)
                   throws IOException

This default implementation validates media types in assertion but writes nothing.

Specified by:

writePrefixTo in interface Encoder

Throws:

IOException

write

public abstract void write(int c,
 Writer out)
                    throws IOException

Specified by:

write in interface Encoder

Throws:

IOException

write

public abstract void write(char[] cbuf,
 Writer out)
                    throws IOException

Specified by:

write in interface Encoder

Throws:

IOException

write

public abstract void write(char[] cbuf,
 int off,
 int len,
 Writer out)
                    throws IOException

Specified by:

write in interface Encoder

Throws:

IOException

write

public abstract void write(String str,
 Writer out)
                    throws IOException

Specified by:

write in interface Encoder

Throws:

IOException

write

public abstract void write(String str,
 int off,
 int len,
 Writer out)
                    throws IOException

Specified by:

write in interface Encoder

Throws:

IOException

append

public abstract MediaEncoder append(char c,
 Appendable out)
                             throws IOException

Specified by:

append in interface Encoder

Throws:

IOException

append

public abstract MediaEncoder append(CharSequence csq,
 Appendable out)
                             throws IOException

Specified by:

append in interface Encoder

Throws:

IOException

append

public abstract MediaEncoder append(CharSequence csq,
 int start,
 int end,
 Appendable out)
                             throws IOException

Specified by:

append in interface Encoder

Throws:

IOException

writeSuffixTo

@Deprecated
public final void writeSuffixTo(Appendable out)
                         throws IOException

Deprecated.

Please use writeSuffixTo(java.lang.Appendable, boolean) while specifying desired trim.

This default implementation calls writeSuffixTo(java.lang.Appendable, boolean) without trimming.

Specified by:

writeSuffixTo in interface Encoder

Throws:

IOException

writeSuffixTo

public void writeSuffixTo(Appendable out,
 boolean trim)
                   throws IOException

This default implementation validates media types in assertion but writes nothing.

Specified by:

writeSuffixTo in interface Encoder

Throws:

IOException