- All Implemented Interfaces:
ValidMediaFilter
,ValidMediaInput
,ValidMediaOutput
,Encoder
- Direct Known Subclasses:
BufferedEncoder
,JavaScriptInXhtmlAttributeEncoder
,JavaScriptInXhtmlEncoder
,StyleInXhtmlAttributeEncoder
,StyleInXhtmlEncoder
,TextInJavaScriptEncoder
,TextInMysqlEncoder
,TextInPsqlEncoder
,TextInShEncoder
,TextInStyleEncoder
,TextInXhtmlAttributeEncoder
,TextInXhtmlEncoder
,ValidateOnlyEncoder
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
-
Method Summary
Modifier and TypeMethodDescriptionabstract 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 ornull
if no encoding is necessary.abstract void
abstract void
abstract void
abstract void
abstract void
void
writePrefixTo
(Appendable out) final void
writeSuffixTo
(Appendable out) Deprecated.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 ornull
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 incontainerType
, and with the same representation. Furthermore, there must be some meaningful relationship betweencontentType
andcontainerType
- 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 anyBufferedEncoder
, which currently is only the encoders forMediaType.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 throwingUnsupportedEncodingException
), 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 forMediaWriter
), can useValidateOnlyEncoder
. - Throws:
UnsupportedEncodingException
- when unable to encode the content into the container either because it is impossible or not yet implemented.
-
writePrefixTo
This default implementation validates media types in assertion but writes nothing.
- Specified by:
writePrefixTo
in interfaceEncoder
- Throws:
IOException
-
write
- Specified by:
write
in interfaceEncoder
- Throws:
IOException
-
write
- Specified by:
write
in interfaceEncoder
- Throws:
IOException
-
write
- Specified by:
write
in interfaceEncoder
- Throws:
IOException
-
write
- Specified by:
write
in interfaceEncoder
- Throws:
IOException
-
write
- Specified by:
write
in interfaceEncoder
- Throws:
IOException
-
append
- Specified by:
append
in interfaceEncoder
- Throws:
IOException
-
append
- Specified by:
append
in interfaceEncoder
- Throws:
IOException
-
append
public abstract MediaEncoder append(CharSequence csq, int start, int end, Appendable out) throws IOException - Specified by:
append
in interfaceEncoder
- Throws:
IOException
-
writeSuffixTo
Deprecated.Please usewriteSuffixTo(java.lang.Appendable, boolean)
while specifying desired trim.This default implementation calls
writeSuffixTo(java.lang.Appendable, boolean)
without trimming.- Specified by:
writeSuffixTo
in interfaceEncoder
- Throws:
IOException
-
writeSuffixTo
This default implementation validates media types in assertion but writes nothing.
- Specified by:
writeSuffixTo
in interfaceEncoder
- Throws:
IOException
-
writeSuffixTo(java.lang.Appendable, boolean)
while specifying desired trim.