com.bigdata.util.httpd

Class MIMEType

java.lang.Object

com.bigdata.util.httpd.MIMEType

public class MIMEType
extends Object

Parser for MIME type data. MIME type, subtype, and MIME parameter names are case-insensitive. Parameters values are treated as case-sensitive by this class, but subclasses may override the comparison logic for parameters, e.g., the "q" parameter in AcceptMIMEType has a default value and its values are compared after conversion into a floating point number.

Field Summary

Fields

Modifier and Type	Field and Description
protected static org.apache.log4j.Logger	log The Logger for MIMEType operations.
protected static Pattern	m_p1 Pattern used to match the type/subtype of a MIME expression.
protected static Pattern	m_p2 Pattern used to match the optional parameters of a MIME expression.

Constructor Summary

Constructors

Constructor and Description
MIMEType(MIMEType mt) Clones the specified MIMEType.
MIMEType(String s) Constructor parses the string as a MIME Internet Type expression.
MIMEType(String type, String subtype) Constructs a MIMEType object from its component parts.
MIMEType(String type, String subtype, NVPair[] params) Constructs a MIMEType object from its component parts.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	equals(Object o) Returns true iff the MIME type, MIME subtype and any MIME parameters are all the same as determined by isExactMatch( MIMEType other, boolean compareParams ) when compareParams is true.
String[]	getDefaultParamNames() Returns the names of all default parameters recognized by this class for the MIME type and subtype represented by this MIMEType instances.
MIMEType	getIntersection(MIMEType other, String[] dropParams) Returns the intersection of the this media-range and the given media-range.
String	getMimeType() Returns the MIME type and subtype as "type/subtype", but does not format in any MIME parameters.
NVPair	getParam(int i) Returns the nth MIME type parameters, origin zero.
int	getParamCount() Returns the #of MIME parameters.
NVPair[]	getParams() An array of the explicitly declared MIME type parameters.
String	getParamValue(String name) Returns the value for the indicated name and null if there is no MIME parameter with that name.
String	getSubtype() Returns the MIME subtype, eg, "plain" for "text/plain".
String	getType() Returns the MIME type, eg, "text" for "text/plain".
protected static void	init() Initialization for shared Pattern object that matches valid MIME type expressions.
boolean	isExactMatch(MIMEType otherType) Convenience method compares type, subtype, and type parameters
boolean	isExactMatch(MIMEType t, boolean compareParams) Returns true IFF the two MIME type expressions have the same meaning.
boolean	isExactMatch(String otherType) Convenience method compares type, subtype, and type parameters
boolean	isIgnoredParam(String name) Returns true iff the named parameter should be ignored by the spans logic for MIME type and subtype represented by this MIMEType instance.
boolean	isSpannedBy(MIMEType other) Convenience method for other.spans( this, true );
boolean	isSpannedBy(MIMEType other, boolean compareParams) Convenience method for other.spans( this, compareParams );
boolean	isSpannedBy(String other) Convenience method for new MIMEType( other ).spans( this, true );
boolean	isSubtypeWildcard() Returns true iff the MIME subtype is "*", indicating a MIME subtype wildcard.
boolean	isTypeWildcard() Returns true iff the MIME type is "*", indicating a MIME type wildcard.
boolean	isWildcard() Deprecated. Use isSubtypeWildcard() instead.
boolean	matches(MIMEType otherMimeType) Convenience method for matches( MIMEType mimeType, boolean matchParams ) that does NOT compare the MIME type parameters.
boolean	matches(MIMEType other, boolean compareParams) Matches if this MIMEType has the same type and subtype or if the types match and this MIMEType is a wildcard that covers the given mimeType.
boolean	matches(String mimeType) Convenience method for matches( MIMEType mimeType, boolean matchParams ) that does NOT compare the MIME type parameters.
boolean	sameParamValue(String name, String realValue, String otherValue) Returns true IFF this MIMEType has the specified parameter value.
boolean	spans(MIMEType other) Convenience method compares type, subtype, and type parameters
boolean	spans(MIMEType other, boolean compareParams) Returns true IFF this MIMEType expresses a constraint that spans the other MIMEType.
boolean	spans(String other) Convenience method compares type, subtype, and type parameters
boolean	spans(String other, boolean compareParams) Convenience method compares type, subtype, and optionally any type parameters.
String	toString() Generates a MIME type string from the parsed data.
String	toString(String name, String value) This method may be extended to produce a specific represensation of the value of the indicated parameter.

Methods inherited from class java.lang.Object

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

Field Detail

log

protected static final org.apache.log4j.Logger log

The Logger for MIMEType operations. The Logger is named for this class.

m_p1

protected static Pattern m_p1

Pattern used to match the type/subtype of a MIME expression. The matched groups are numbered by the opening parentheses in the pattern. The different matching groups are:

• group(0) : the matched input.
• group(1) : type
• group(2) : subtype
• group(3) : the rest of the input, to which you then apply m_p2.

m_p2

protected static Pattern m_p2

Pattern used to match the optional parameters of a MIME expression. The matched groups are numbered by the opening parentheses in the pattern. The source for the pattern is the parameters as identified by m_p1. The different matching groups are:

• group( 0 ) : parameter ( attribute=value ).
• group( 1 ) : attribute (parameter name).
• group( 2 ) : value for that parameter.

Note: You should match this pattern repeatedly until the input is exhausted.

Constructor Detail

MIMEType

public MIMEType(MIMEType mt)

Clones the specified MIMEType.

MIMEType

public MIMEType(String type,
        String subtype)

Constructs a MIMEType object from its component parts. The MIMEType will not have any MIME attributes.

MIMEType

public MIMEType(String type,
        String subtype,
        NVPair[] params)
         throws IllegalArgumentException

Constructs a MIMEType object from its component parts.

Parameters:

type - The media type or "*" (if the subtype if also "*").

subtype - The media subtype or "*".

params - An array of name-value pairs specifying the MIME attributes.

Throws:

IllegalArgumentException - If the method is unable to validate the syntax of the type, subtype and params. Everything must be an HTTP token except the attribute value, which is interchanged as an HTTP quoted-string any may contain pretty much any character sequence. Also thrown if params is null.

MIMEType

public MIMEType(String s)
         throws IllegalArgumentException

Constructor parses the string as a MIME Internet Type expression. The results of the parse are available from the various methods on the constructed object.

From the HTTP/1.1 specification: The type, subtype, and parameter attribute names are case-insensitive. Parameter values might or might not be casesensitive, depending on the semantics of the parameter name. Linear white space (LWS) MUST NOT be used between the type and subtype, nor between an attribute and its value.

Throws:

IllegalArgumentException - Indicates that the string could not be parsed as a valid MIME expression.

Method Detail

init

protected static void init()

Initialization for shared Pattern object that matches valid MIME type expressions.

getDefaultParamNames

public String[] getDefaultParamNames()

Returns the names of all default parameters recognized by this class for the MIME type and subtype represented by this MIMEType instances.

Returns:

The default implementation always returns an empty String[] since it does not recognize any default MIME type parameters. Implementors that subclass MIMEType MUST extend this method if the subclass recognizes any default MIME type parameters.

isIgnoredParam

public boolean isIgnoredParam(String name)

Returns true iff the named parameter should be ignored by the spans logic for MIME type and subtype represented by this MIMEType instance.

Returns:

The default implementation always returns false. Implementors that subclass MIMEType MUST extend this method if the subclass contains any parameters that should be ignored by the spans logic.

getType

public String getType()

Returns the MIME type, eg, "text" for "text/plain".

getSubtype

public String getSubtype()

Returns the MIME subtype, eg, "plain" for "text/plain".

isTypeWildcard

public boolean isTypeWildcard()

Returns true iff the MIME type is "*", indicating a MIME type wildcard.

isWildcard

public boolean isWildcard()

Deprecated. Use isSubtypeWildcard() instead.

Returns true iff the MIME subtype is "*", indicating a MIME wildcard.

isSubtypeWildcard

public boolean isSubtypeWildcard()

Returns true iff the MIME subtype is "*", indicating a MIME subtype wildcard.

getMimeType

public String getMimeType()

Returns the MIME type and subtype as "type/subtype", but does not format in any MIME parameters.

Note: There is no LWS (linear whitespace) between the type and the subtype for a MIME string.

See Also:

toString()

matches

public boolean matches(String mimeType)
                throws IllegalArgumentException

Convenience method for matches( MIMEType mimeType, boolean matchParams ) that does NOT compare the MIME type parameters.

Throws:

IllegalArgumentException

matches

public boolean matches(MIMEType otherMimeType)
                throws IllegalArgumentException

Convenience method for matches( MIMEType mimeType, boolean matchParams ) that does NOT compare the MIME type parameters.

Throws:

IllegalArgumentException

isExactMatch

public boolean isExactMatch(MIMEType otherType)

Convenience method compares type, subtype, and type parameters

isExactMatch

public boolean isExactMatch(String otherType)
                     throws IllegalArgumentException

Convenience method compares type, subtype, and type parameters

Throws:

IllegalArgumentException

isExactMatch

public boolean isExactMatch(MIMEType t,
                   boolean compareParams)

Returns true IFF the two MIME type expressions have the same meaning. I.e., they impose the same type and subtype constraint and, optionally, they impose the same MIME type parameter constraints (if any). The MIME type and subtype and MIME parameter names are compared using case-insensitive comparison.

Note: The MIME parameter values are compared using a case-sensitive comparison, which is not correct for all MIME types since some explictly provide for case-insensitive semantics for their parameter values. Implementors are free to further specialize this method in derived subclasses to obtain MIME type specific comparision of MIME type parameter values or to establish default parameter values.

Note: Defaults may be provided for MIME parameters through subclasses by extending ( String name, String realValue, String otherValue ), getDefaultParamNames(), and #isIgnoredParamName( String name ).

sameParamValue

public boolean sameParamValue(String name,
                     String realValue,
                     String otherValue)
                       throws IllegalArgumentException

Returns true IFF this MIMEType has the specified parameter value. This method is exposed to account for any MIME type specific case-sensitivity for the parameter name or parameter value and any default MIME type parameters.

The default implementation uses a case-sensitive comparison of the MIME parameter value. Implementors are free to created subclasses that extend this method to incorporate MIME type specific logic in their comparison.

Parameters:

name - The name of the parameter whose value is being compared. This parameter is ignored by this implementation but is provided for subclasses that may have type specific value comparison logic and/or parameter value default logic.

realValue - The value of the parameter on this MIMEType object as discovered, e.g., by getParamValue( String name ). This may explicitly be null. Subclasses that have a default value for this named parameter, e.g., AcceptMIMEType which has a default value for the "q" parameter, MUST substitute their default value when realValue is null.

otberValue - The value that is being compared to the foundValue. This parameter MAY be null, in which case a subclass MAY choose to declare a default value to be used in this comparison.

Throws:

IllegalArgumentException

toString

public String toString(String name,
              String value)

This method may be extended to produce a specific represensation of the value of the indicated parameter. The representation returned will still be quoted iff necessary for HTTP by toString() when serializing the entire header value.

getIntersection

public MIMEType getIntersection(MIMEType other,
                       String[] dropParams)

Returns the intersection of the this media-range and the given media-range. The resulting MIMEType MAY be a fully determined media type, but it MAY be undetermined, e.g., has a type or subtype wildcard, does not specify a content encoding, language family, etc. If this is NOT a fully determined media type, then the server MUST make it into a concrete media type.

Parameters:

other - The other media-range whose intersection with this media-range will be return.

dropParams - An array of zero or more parameter names that will be dropped out of the intersected media-ranges. For example, this is used to drop the "q" parameter during content negotiation when computing the negotiated joint media-range.

Returns:

The intersection of the two media-ranges or null if the intersection does not exist. For example, if the two media-ranges each specify different concrete subtypes, such as "text/xml" vs "text/plain".

spans

public boolean spans(String other)

Convenience method compares type, subtype, and type parameters

spans

public boolean spans(MIMEType other)

Convenience method compares type, subtype, and type parameters

spans

public boolean spans(String other,
            boolean compareParams)

Convenience method compares type, subtype, and optionally any type parameters.

spans

public boolean spans(MIMEType other,
            boolean compareParams)

Returns true IFF this MIMEType expresses a constraint that spans the other MIMEType. The semantics of "spans" are that the other may be either the same MIMEType or may be a more constrained (aka specific) MIMEType.

Parameters:

compareParams - IFF true the MIME type parameters are also compared by this method. The specific parameter values are compared using sameParamValue( String name, String realValue, String otherValue ).

isSpannedBy

public boolean isSpannedBy(String other)

Convenience method for new MIMEType( other ).spans( this, true );

isSpannedBy

public boolean isSpannedBy(MIMEType other)

Convenience method for other.spans( this, true );

isSpannedBy

public boolean isSpannedBy(MIMEType other,
                  boolean compareParams)

Convenience method for other.spans( this, compareParams );

matches

public boolean matches(MIMEType other,
              boolean compareParams)

Matches if this MIMEType has the same type and subtype or if the types match and this MIMEType is a wildcard that covers the given mimeType. The parameters are optionally compared by this method.

Parameters:

compareParams - IFF true the MIME type parameters are also compared by this method. The specific parameter values are compared using sameParamValue( String name, String realValue, String otherValue ). Note: This is a convenience for spans( other, false );.

See Also:

spans( MIMEType other, boolean compareParams )

equals

public boolean equals(Object o)

Returns true iff the MIME type, MIME subtype and any MIME parameters are all the same as determined by isExactMatch( MIMEType other, boolean compareParams ) when compareParams is true.

Overrides:

equals in class Object

Parameters:

o - Must be a String or MIMEType object.

getParams

public NVPair[] getParams()

An array of the explicitly declared MIME type parameters. Default parameters are NOT represented in the returned array.

getParam

public NVPair getParam(int i)

Returns the nth MIME type parameters, origin zero.

getParamCount

public int getParamCount()

Returns the #of MIME parameters.

getParamValue

public String getParamValue(String name)

Returns the value for the indicated name and null if there is no MIME parameter with that name.

Parameters:

name - The name of a MIME parameter, which is case-insensitive. Implementors can create subclasses if a specific MIME type declares some case-sensitive MIME type parameter names.

toString

public String toString()

Generates a MIME type string from the parsed data. If any parameter value is not a valid HTTP token then it is serialized as an HTTP quoted-string.

Note: There is no LWS (linear whitespace) between the type and the subtype for a MIME string. Also, there is no LWS between the attribute name and the attribute value, e.g., "charset=xxx" but not "charset = xxx".

Overrides:

toString in class Object