dev@fi.java.net

Proposed API for SAX encoding algorithm support

From: Paul Sandoz <Paul.Sandoz_at_Sun.COM>
Date: Thu, 27 Jan 2005 14:45:59 +0100

Hi,

See attached javadoc for a much simpler SAX API for encoding algorithm
of content and attributes.

I believe we can use these same concepts for StAX.

Alan, does this meet your requirements for X3D?


For application defined encoding algorithms we still need to resolve how
objects other than byte[] are returned but that will not change the
methods or parameters of these APIs.

Paul. 

-- 
| ? + ? = To question
----------------\
    Paul Sandoz
         x38109
+33-4-76188109
EncodingAlgorithmIndexes
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.xml.fastinfoset.api
Class EncodingAlgorithmIndexes

java.lang.Object
  extended by com.sun.xml.fastinfoset.api.EncodingAlgorithmIndexes

public final class EncodingAlgorithmIndexes
extends java.lang.Object

The indexes of built-in encoding algorithms.

The indexes of the built-in encoding algorithms are specified in ITU-T Rec. X.891 | ISO/IEC 24824-1 (Fast Infoset), clause 10.

Version:
0.1
See Also:
AlphabetAndAlgorithmContentHandler

Field Summary
static int BASE64
           
static int BOOLEAN
           
static int CDATA
           
static int DOUBLE
           
static int FLOAT
           
static int HEXADECIMAL
           
static int INT
           
static int LONG
           
static int SHORT
           
static int UUID
           
 
Constructor Summary
EncodingAlgorithmIndexes()
           
 
Method Summary
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

HEXADECIMAL

public static final int HEXADECIMAL
See Also:
Constant Field Values

BASE64

public static final int BASE64
See Also:
Constant Field Values

SHORT

public static final int SHORT
See Also:
Constant Field Values

INT

public static final int INT
See Also:
Constant Field Values

LONG

public static final int LONG
See Also:
Constant Field Values

BOOLEAN

public static final int BOOLEAN
See Also:
Constant Field Values

FLOAT

public static final int FLOAT
See Also:
Constant Field Values

DOUBLE

public static final int DOUBLE
See Also:
Constant Field Values

UUID

public static final int UUID
See Also:
Constant Field Values

CDATA

public static final int CDATA
See Also:
Constant Field Values
Constructor Detail

EncodingAlgorithmIndexes

public EncodingAlgorithmIndexes()
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
FastInfosetReader
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.xml.fastinfoset.api.sax
Interface FastInfosetReader

public interface FastInfosetReader

Interface for reading an Fast Infoset document using callbacks.

FastInfosetReader is the interface that an Fast Infoset parser's SAX2 driver must implement. This interface allows an application to to register Fast Infoset specific event handlers for encoding algorithms.

The support for encoding algorithms is categorised into four categories: 1) None ; 2) Generic; 3) Primitive; and 4) Primitive and application. The category of support is enabled by the registration (or not) of EncodingAlgorithmContentHandler and PrimitiveTypeContentHandler as follows.

"None": If the EncodingAlgorithmContentHandler and PrimitiveTypeContentHandler are not registered then encoding algorithm data for the built-in encoding algorithms shall be notified as character data using the characters method. The occurence of encoding algorithm data for application defined encoding algorithms shall result in the throwing of a java.io.IOException.

"Generic": If the EncodingAlgorithmContentHandler is registered and the PrimitiveTypeContentHandler is not registered then encoding algorithm data for the built-in and application defined encoding algorithms shall be notified through the callback methods of the EncodingAlgorithmContentHandler.

"Primitive": If the EncodingAlgorithmContentHandler is not registered and the PrimitiveTypeContentHandler is registered then encoding algorithm data for the built-in encoding algorithms shall be notified through the callback methods of the PrimitiveTypeContentHandler. The occurence of encoding algorithm data for application defined encoding algorithms shall result in the throwing of a java.io.IOException.

"Primitive and application": If the EncodingAlgorithmContentHandler and PrimitiveTypeContentHandler are registered then then encoding algorithm data for the built-in encoding algorithms shall be notified through the callback methods of the PrimitiveTypeContentHandler, and the encoding algorithm data for the application defined encoding algorithms shall be notified through the callback methods of the EncodingAlgorithmContentHandler.

Version:
0.1
See Also:
PrimitiveTypeContentHandler, EncodingAlgorithmContentHandler, XMLReader, ContentHandler

Method Summary
 EncodingAlgorithmContentHandler getEncodingAlgorithmContentHandler()
          Return the current encoding algorithm handler.
 PrimitiveTypeContentHandler getPrimitiveTypeContentHandler()
          Return the current primitive type handler.
 void setEncodingAlgorithmContentHandler(EncodingAlgorithmContentHandler handler)
          Allow an application to register an encoding algorithm handler.
 void setPrimitiveTypeContentHandler(PrimitiveTypeContentHandler handler)
          Allow an application to register a primitive type handler.
 

Method Detail

setEncodingAlgorithmContentHandler

void setEncodingAlgorithmContentHandler(EncodingAlgorithmContentHandler handler)
Allow an application to register an encoding algorithm handler.

If the application does not register an encoding algorithm handler, TODO

Applications may register a new or different handler in the middle of a parse, and the SAX parser must begin using the new handler immediately.

Parameters:
handler - The encoding algorithm handler.
See Also:
getEncodingAlgorithmContentHandler()

getEncodingAlgorithmContentHandler

EncodingAlgorithmContentHandler getEncodingAlgorithmContentHandler()
Return the current encoding algorithm handler.

Returns:
The current encoding algorithm handler, or null if none has been registered.
See Also:
setEncodingAlgorithmContentHandler(com.sun.xml.fastinfoset.api.sax.EncodingAlgorithmContentHandler)

setPrimitiveTypeContentHandler

void setPrimitiveTypeContentHandler(PrimitiveTypeContentHandler handler)
Allow an application to register a primitive type handler.

If the application does not register a primitive type handler, TODO

Applications may register a new or different handler in the middle of a parse, and the SAX parser must begin using the new handler immediately.

Parameters:
handler - The primitive type handler.
See Also:
#gettPrimitiveTypeContentHandler

getPrimitiveTypeContentHandler

PrimitiveTypeContentHandler getPrimitiveTypeContentHandler()
Return the current primitive type handler.

Returns:
The current primitive type handler, or null if none has been registered.
See Also:
setPrimitiveTypeContentHandler(com.sun.xml.fastinfoset.api.sax.PrimitiveTypeContentHandler)
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
EncodingAlgorithmContentHandler
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.xml.fastinfoset.api.sax
Interface EncodingAlgorithmContentHandler

public interface EncodingAlgorithmContentHandler

SAX2 extention handler to receive notification of encoding algorithm data.

This is an optional extension handler for SAX2. XML readers are not required to recognize this handler, and it is not part of core-only SAX2 distributions.

This interface may be used with with a Fast Infoset SAX parser to receive notification of encoding algorithm data specified in ITU-T Rec. X.891 | ISO/IEC 24824-1 (Fast Infoset) clause 10 and for application defined encoding algorithms specified as part of the initial vocabulary of a fast infoset document.

To set the EncodingAlgorithmContentHandler for an XML reader, use the setProperty method with the property name URI TO BE DEFINED and an object implementing this interface (or null) as the value. If the reader does not report primitive data types, it will throw a SAXNotRecognizedException

To set the EncodingAlgorithmContentHandler for an Fast Infoset reader, use setEncodingAlgorithmContentHandler method.

Version:
0.1
See Also:
PrimitiveTypeContentHandler, FastInfosetReader, XMLReader

Method Summary
 void object(java.lang.String URI, int algorithm, java.lang.Object o)
          Receive notification of encoding algorithm data as an object.
 void octets(java.lang.String URI, int algorithm, byte[] b, int start, int length)
          Receive notification of encoding algorithm data as an array of byte.
 

Method Detail

octets

void octets(java.lang.String URI,
            int algorithm,
            byte[] b,
            int start,
            int length)
            throws org.xml.sax.SAXException
Receive notification of encoding algorithm data as an array of byte.

The application must not attempt to read from the array outside of the specified range.

Such notifications will occur for a Fast Infoset SAX parser when processing encoding algorithm data.

The Parser will call the method of this interface to report each encoding algorithm data. Parsers MUST return all contiguous characters in a single chunk

Parsers may return all contiguous bytes in a single chunk, or they may split it into several chunks providing that the length of each chunk is of the required length to successfully apply the encoding algorithm to the chunk.

Parameters:
URI - the URI of the encoding algorithm
algorithm - the encoding algorithm index
b - the array of byte
start - the start position in the array
length - the number of byte to read from the array
Throws:
org.xml.sax.SAXException - any SAX exception, possibly wrapping another exception
See Also:
com.sun.xml.fastinfoset.EncodingAlgorithmIndexes

object

void object(java.lang.String URI,
            int algorithm,
            java.lang.Object o)
            throws org.xml.sax.SAXException
Receive notification of encoding algorithm data as an object.

Such notifications will occur for a Fast Infoset SAX parser when processing encoding algorithm data that is converted from an array of byte to an object more suitable for processing.

Parameters:
URI - the URI of the encoding algorithm
algorithm - the encoding algorithm index
o - the encoding algorithm object
Throws:
org.xml.sax.SAXException - any SAX exception, possibly wrapping another exception
See Also:
com.sun.xml.fastinfoset.EncodingAlgorithmIndexes
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
PrimitiveTypeContentHandler
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.xml.fastinfoset.api.sax
Interface PrimitiveTypeContentHandler

public interface PrimitiveTypeContentHandler

SAX2 extention handler to receive notification of character data as primtive types.

This is an optional extension handler for SAX2. XML readers are not required to recognize this handler, and it is not part of core-only SAX2 distributions.

This interface may be used with with a Fast Infoset SAX parser to receive notification of data encoded using the following built-in encoding algorithms specified in ITU-T Rec. X.891 | ISO/IEC 24824-1 (Fast Infoset), clause 10: "boolean", "base64", "short", "int", "long", "float", "double" and "uuid" encoding algorithms.

To set the PrimitiveTypeContentHandler for an XML reader, use the setProperty method with the property name URI TO BE DEFINED and an object implementing this interface (or null) as the value. If the reader does not report primitive data types, it will throw a SAXNotRecognizedException

To set the PrimitiveTypeContentHandler for an Fast Infoset reader, use setPrimitiveTypeContentHandler method.

The Parser will call methods of this interface to report each chunk of character data that has been converted to an array of primitive types, for example an array of integer or an array of float. Parsers may return all contiguous primtive types in a single chunk, or they may split it into several chunks

The application must not attempt to read from the array outside of the specified range.

Version:
0.1
See Also:
EncodingAlgorithmContentHandler, FastInfosetReader, XMLReader

Method Summary
 void booleans(boolean[] b, int start, int length)
          Receive notification of character data as an array of boolean.
 void bytes(byte[] b, int start, int length)
          Receive notification of character data as an array of byte.
 void doubles(double[] d, int start, int length)
          Receive notification of character data as an array of double.
 void floats(float[] f, int start, int length)
          Receive notification of character data as an array of float.
 void ints(int[] i, int start, int length)
          Receive notification of character data as an array of int.
 void longs(long[] l, int start, int length)
          Receive notification of character data as an array of long.
 void shorts(short[] s, int start, int length)
          Receive notification of character data as an array of short.
 void uuids(long[] msb, long[] lsb, int start, int length)
          Receive notification of character data as an two array of UUID.
 

Method Detail

booleans

void booleans(boolean[] b,
              int start,
              int length)
              throws org.xml.sax.SAXException
Receive notification of character data as an array of boolean.

The application must not attempt to read from the array outside of the specified range.

Such notifications will occur for a Fast Infoset SAX parser when processing data encoded using the "boolean" encoding algorithm, see subclause 10.7

.

Parameters:
b - the array of boolean
start - the start position in the array
length - the number of boolean to read from the array
Throws:
org.xml.sax.SAXException - any SAX exception, possibly wrapping another exception

bytes

void bytes(byte[] b,
           int start,
           int length)
           throws org.xml.sax.SAXException
Receive notification of character data as an array of byte.

The application must not attempt to read from the array outside of the specified range.

Such notifications will occur for a Fast Infoset SAX parser when processing data encoded using the "base64" encoding algorithm, see subclause 10.3.

Such a notification may occur for binary data that would normally require base 64 encoding and reported as character data using the characters method

.

Parameters:
b - the array of byte
start - the start position in the array
length - the number of byte to read from the array
Throws:
org.xml.sax.SAXException - any SAX exception, possibly wrapping another exception

shorts

void shorts(short[] s,
            int start,
            int length)
            throws org.xml.sax.SAXException
Receive notification of character data as an array of short.

The application must not attempt to read from the array outside of the specified range.

Such notifications will occur for a Fast Infoset SAX parser when processing data encoded using the "short" encoding algorithm, see subclause 10.4

.

Parameters:
s - the array of short
start - the start position in the array
length - the number of short to read from the array
Throws:
org.xml.sax.SAXException - any SAX exception, possibly wrapping another exception

ints

void ints(int[] i,
          int start,
          int length)
          throws org.xml.sax.SAXException
Receive notification of character data as an array of int.

The application must not attempt to read from the array outside of the specified range.

Such notifications will occur for a Fast Infoset SAX parser when processing data encoded using the "int" encoding algorithm, see subclause 10.5

.

Parameters:
i - the array of int
start - the start position in the array
length - the number of int to read from the array
Throws:
org.xml.sax.SAXException - any SAX exception, possibly wrapping another exception

longs

void longs(long[] l,
           int start,
           int length)
           throws org.xml.sax.SAXException
Receive notification of character data as an array of long.

The application must not attempt to read from the array outside of the specified range.

Such notifications will occur for a Fast Infoset SAX parser when processing data encoded using the "long" encoding algorithm, see subclause 10.6

.

Parameters:
l - the array of long
start - the start position in the array
length - the number of long to read from the array
Throws:
org.xml.sax.SAXException - any SAX exception, possibly wrapping another exception

floats

void floats(float[] f,
            int start,
            int length)
            throws org.xml.sax.SAXException
Receive notification of character data as an array of float.

The application must not attempt to read from the array outside of the specified range.

Such notifications will occur for a Fast Infoset SAX parser when processing data encoded using the "float" encoding algorithm, see subclause 10.8

.

Parameters:
f - the array of float
start - the start position in the array
length - the number of float to read from the array
Throws:
org.xml.sax.SAXException - any SAX exception, possibly wrapping another exception

doubles

void doubles(double[] d,
             int start,
             int length)
             throws org.xml.sax.SAXException
Receive notification of character data as an array of double.

The application must not attempt to read from the array outside of the specified range.

Such notifications will occur for a Fast Infoset SAX parser when processing data encoded using the "double" encoding algorithm, see subclause 10.9

.

Parameters:
d - the array of double
start - the start position in the array
length - the number of double to read from the array
Throws:
org.xml.sax.SAXException - any SAX exception, possibly wrapping another exception

uuids

void uuids(long[] msb,
           long[] lsb,
           int start,
           int length)
           throws org.xml.sax.SAXException
Receive notification of character data as an two array of UUID.

The application must not attempt to read from the array outside of the specified range.

Such notifications will occur for a Fast Infoset SAX parser when processing data encoded using the "uuid" encoding algorithm, see subclause 10.10

.

Parameters:
msb - the array of long of the most sigificant bits of the UUIDs
lsb - the array of long of the least sigificant bits of the UUIDs
start - the start position in the array
length - the number of UUID to read from the array
Throws:
org.xml.sax.SAXException - any SAX exception, possibly wrapping another exception
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
EncodingAlgorithmAttributes
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.xml.fastinfoset.api.sax
Interface EncodingAlgorithmAttributes

All Superinterfaces:
org.xml.sax.Attributes
public interface EncodingAlgorithmAttributes
extends org.xml.sax.Attributes

Interface for a list of XML attributes that may contain encoding algorithm data.

Version:
0.1
See Also:
FastInfosetReader, XMLReader

Method Summary
 java.lang.Object getAlgorithmData(int index)
          Return the data of the encoding algorithm.
 int getAlgorithmIndex(int index)
          Return the index of the encoding algorithm
 java.lang.String getAlgorithmURI(int index)
          Return the URI of the encoding algorithm.
 
Methods inherited from interface org.xml.sax.Attributes
getIndex, getIndex, getLength, getLocalName, getQName, getType, getType, getType, getURI, getValue, getValue, getValue
 

Method Detail

getAlgorithmURI

java.lang.String getAlgorithmURI(int index)
Return the URI of the encoding algorithm.

If the encoding algorithm support is "None" then rull is returned.

If "Generic" and "Primitive and application" then null is returned if the encoding algorithm data is for a built-in encoding algorithm and the URI is returned for an application defined encoding algorithm.

If "Primitive" then null is returned.

Parameters:
index - The attribute index (zero-based).
Returns:
The URI.

getAlgorithmIndex

int getAlgorithmIndex(int index)
Return the index of the encoding algorithm

If the encoding algorithm support is "None" then 0 is returned.

If "Generic" and "Primitive and application" then the index of the built-in or application defined encoding algorithm is returned.

If "Primitive" then the index of the built-in encoding algorithm is returned, otherwise 0 is returned.

Parameters:
index - The attribute index (zero-based).
Returns:
The index
See Also:
com.sun.xml.fastinfoset.EncodingAlgorithmIndexes

getAlgorithmData

java.lang.Object getAlgorithmData(int index)
Return the data of the encoding algorithm.

If the encoding algorithm support is "None" then null is returned.

If "Generic" then a byte[] object is returned for built-in and application defined encoding algorithms.

If "Primitive" then an object that is an array of the primitive type is returned for a built-in encoding algorithm, otherwise null is returned.

If "Primitive and application" then an object that is an array of the primitive type is returned for a built-in encoding algorithm and a byte[] object is returned for application defined encoding algorithms.

Parameters:
index - The attribute index (zero-based).
Returns:
The data
See Also:
com.sun.xml.fastinfoset.EncodingAlgorithmIndexes
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

/*
 * Fast Infoset ver. 0.1 software ("Software")
 *
 * Copyright, 2004-2005 Sun Microsystems, Inc. All Rights Reserved.
 *
 * Software is licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. You may
 * obtain a copy of the License at:
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations.
 *
 * Sun supports and benefits from the global community of open source
 * developers, and thanks the community for its important contributions and
 * open standards-based technology, which Sun has adopted into many of its
 * products.
 *
 * Please note that portions of Software may be provided with notices and
 * open source licenses from such communities and third parties that govern the
 * use of those portions, and any licenses granted hereunder do not alter any
 * rights and obligations you may have under such open source licenses,
 * however, the disclaimer of warranty and limitation of liability provisions
 * in this License will apply to all Software in this distribution.
 *
 * You acknowledge that the Software is not designed, licensed or intended
 * for use in the design, construction, operation or maintenance of any nuclear
 * facility.
 *
 * Apache License
 * Version 2.0, January 2004
 * http://www.apache.org/licenses/
 *
 */

package com.sun.xml.fastinfoset.api;

/**
 * The indexes of built-in encoding algorithms.
 *
 * <p>The indexes of the built-in encoding algorithms are specified
 * in ITU-T Rec. X.891 | ISO/IEC 24824-1 (Fast Infoset), clause
 * 10.<p>
 *
 * @version 0.1
 * @see com.sun.xml.fastinfoset.api.sax.AlphabetAndAlgorithmContentHandler
 */
public final class EncodingAlgorithmIndexes {
    public static final int HEXADECIMAL = 1;
    public static final int BASE64 = 2;
    public static final int SHORT = 3;
    public static final int INT = 4;
    public static final int LONG = 5;
    public static final int BOOLEAN = 6;
    public static final int FLOAT = 7;
    public static final int DOUBLE = 8;
    public static final int UUID = 9;
    public static final int CDATA = 10;
}


/*
 * Fast Infoset ver. 0.1 software ("Software")
 *
 * Copyright, 2004-2005 Sun Microsystems, Inc. All Rights Reserved.
 *
 * Software is licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. You may
 * obtain a copy of the License at:
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations.
 *
 * Sun supports and benefits from the global community of open source
 * developers, and thanks the community for its important contributions and
 * open standards-based technology, which Sun has adopted into many of its
 * products.
 *
 * Please note that portions of Software may be provided with notices and
 * open source licenses from such communities and third parties that govern the
 * use of those portions, and any licenses granted hereunder do not alter any
 * rights and obligations you may have under such open source licenses,
 * however, the disclaimer of warranty and limitation of liability provisions
 * in this License will apply to all Software in this distribution.
 *
 * You acknowledge that the Software is not designed, licensed or intended
 * for use in the design, construction, operation or maintenance of any nuclear
 * facility.
 *
 * Apache License
 * Version 2.0, January 2004
 * http://www.apache.org/licenses/
 *
 */

package com.sun.xml.fastinfoset.api.sax;

/**
 * Interface for reading an Fast Infoset document using callbacks.
 *
 * <p>FastInfosetReader is the interface that an Fast Infoset parser's
 * SAX2 driver must implement. This interface allows an application to
 * to register Fast Infoset specific event handlers for encoding algorithms.</p>
 *
 * <p>The support for encoding algorithms is categorised into four categories:
 * 1) None ; 2) Generic; 3) Primitive; and 4) Primitive and application. The
 * category of support is enabled by the registration (or not) of
 * EncodingAlgorithmContentHandler and PrimitiveTypeContentHandler as follows.<p>
 *
 * <p>"None": If the EncodingAlgorithmContentHandler and PrimitiveTypeContentHandler are
 * not registered then encoding algorithm data for the built-in encoding
 * algorithms shall be notified as character data using the
 * {_at_link org.xml.sax.ContentHandler#characters characters } method. The occurence
 * of encoding algorithm data for application defined encoding algorithms
 * shall result in the throwing of a java.io.IOException.<p>
 *
 * <p>"Generic": If the EncodingAlgorithmContentHandler is registered and the
 * PrimitiveTypeContentHandler is not registered then encoding algorithm data
 * for the built-in and application defined encoding algorithms shall be notified
 * through the callback methods of the EncodingAlgorithmContentHandler.<p>
 *
 * <p>"Primitive": If the EncodingAlgorithmContentHandler is not registered and the
 * PrimitiveTypeContentHandler is registered then encoding algorithm data
 * for the built-in encoding algorithms shall be notified through the callback
 * methods of the PrimitiveTypeContentHandler. The occurence of encoding
 * algorithm data for application defined encoding algorithms shall
 * result in the throwing of a java.io.IOException.<p>
 *
 * <p>"Primitive and application": If the EncodingAlgorithmContentHandler
 * and PrimitiveTypeContentHandler are registered then then encoding algorithm
 * data for the built-in encoding algorithms shall be notified through the
 * callback methods of the PrimitiveTypeContentHandler, and the encoding
 * algorithm data for the application defined encoding algorithms shall be
 * notified through the callback methods of the EncodingAlgorithmContentHandler.<p>
 *
 * @version 0.1
 * @see com.sun.xml.fastinfoset.api.sax.PrimitiveTypeContentHandler
 * @see com.sun.xml.fastinfoset.api.sax.EncodingAlgorithmContentHandler
 * @see org.xml.sax.XMLReader
 * @see org.xml.sax.ContentHandler
 */
public interface FastInfosetReader {
    /**
     * Allow an application to register an encoding algorithm handler.
     *
     * <p>If the application does not register an encoding algorithm handler,
     * TODO</p>
     *
     * <p>Applications may register a new or different handler in the
     * middle of a parse, and the SAX parser must begin using the new
     * handler immediately.</p>
     *
     * @param handler The encoding algorithm handler.
     * @see #getEncodingAlgorithmContentHandler
     */
    public void setEncodingAlgorithmContentHandler(EncodingAlgorithmContentHandler handler);


    /**
     * Return the current encoding algorithm handler.
     *
     * @return The current encoding algorithm handler, or null if none
     * has been registered.
     * @see #setEncodingAlgorithmContentHandler
     */
    public EncodingAlgorithmContentHandler getEncodingAlgorithmContentHandler();

    /**
     * Allow an application to register a primitive type handler.
     *
     * <p>If the application does not register a primitive type handler,
     * TODO</p>
     *
     * <p>Applications may register a new or different handler in the
     * middle of a parse, and the SAX parser must begin using the new
     * handler immediately.</p>
     *
     * @param handler The primitive type handler.
     * @see #gettPrimitiveTypeContentHandler
     */
    public void setPrimitiveTypeContentHandler(PrimitiveTypeContentHandler handler);


    /**
     * Return the current primitive type handler.
     *
     * @return The current primitive type handler, or null if none
     * has been registered.
     * @see #setPrimitiveTypeContentHandler
     */
    public PrimitiveTypeContentHandler getPrimitiveTypeContentHandler();
    
}


/*
 * Fast Infoset ver. 0.1 software ("Software")
 *
 * Copyright, 2004-2005 Sun Microsystems, Inc. All Rights Reserved.
 *
 * Software is licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. You may
 * obtain a copy of the License at:
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations.
 *
 * Sun supports and benefits from the global community of open source
 * developers, and thanks the community for its important contributions and
 * open standards-based technology, which Sun has adopted into many of its
 * products.
 *
 * Please note that portions of Software may be provided with notices and
 * open source licenses from such communities and third parties that govern the
 * use of those portions, and any licenses granted hereunder do not alter any
 * rights and obligations you may have under such open source licenses,
 * however, the disclaimer of warranty and limitation of liability provisions
 * in this License will apply to all Software in this distribution.
 *
 * You acknowledge that the Software is not designed, licensed or intended
 * for use in the design, construction, operation or maintenance of any nuclear
 * facility.
 *
 * Apache License
 * Version 2.0, January 2004
 * http://www.apache.org/licenses/
 *
 */

package com.sun.xml.fastinfoset.api.sax;

import org.xml.sax.SAXException;

/**
 * SAX2 extention handler to receive notification of encoding algorithm data.
 *
 * <p>This is an optional extension handler for SAX2. XML readers are not
 * required to recognize this handler, and it is not part of core-only
 * SAX2 distributions.</p>
 *
 * <p>This interface may be used with with a Fast Infoset
 * SAX parser to receive notification of encoding algorithm data specified
 * in ITU-T Rec. X.891 | ISO/IEC 24824-1 (Fast Infoset) clause 10 and for
 * application defined encoding algorithms specified as part of the
 * initial vocabulary of a fast infoset document.<p>
 *
 * <p>To set the EncodingAlgorithmContentHandler for an XML reader, use the
 * {_at_link org.xml.sax.XMLReader#setProperty setProperty} method
 * with the property name
 * <code>URI TO BE DEFINED</code>
 * and an object implementing this interface (or null) as the value.
 * If the reader does not report primitive data types, it will throw a
 * {_at_link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException}</p>
 *
 * <p>To set the EncodingAlgorithmContentHandler for an Fast Infoset reader, use
 * {_at_link com.sun.xml.fastinfoset.api.sax.FastInfosetReader#setEncodingAlgorithmContentHandler
 * setEncodingAlgorithmContentHandler} method.<p>
 *
 * @version 0.1
 * @see com.sun.xml.fastinfoset.api.sax.PrimitiveTypeContentHandler
 * @see com.sun.xml.fastinfoset.api.sax.FastInfosetReader
 * @see org.xml.sax.XMLReader
 */
public interface EncodingAlgorithmContentHandler {
    /**
     * Receive notification of encoding algorithm data as an array
     * of byte.
     *
     * <p>The application must not attempt to read from the array
     * outside of the specified range.</p>
     *
     * <p>Such notifications will occur for a Fast Infoset SAX parser
     * when processing encoding algorithm data.<p>
     *
     * <p>The Parser will call the method of this interface to report each
     * encoding algorithm data. Parsers MUST return all contiguous
     * characters in a single chunk</p>
     *
     * <p>Parsers may return all contiguous bytes in a single chunk, or
     * they may split it into several chunks providing that the length of
     * each chunk is of the required length to successfully apply the
     * encoding algorithm to the chunk.</p>
     *
     * @param URI the URI of the encoding algorithm
     * @param algorithm the encoding algorithm index
     * @param b the array of byte
     * @param start the start position in the array
     * @param length the number of byte to read from the array
     * @throws org.xml.sax.SAXException any SAX exception, possibly
     * wrapping another exception
     * @see com.sun.xml.fastinfoset.EncodingAlgorithmIndexes
     */
    void octets(String URI, int algorithm, byte[] b, int start, int length) throws SAXException;

    /**
     * Receive notification of encoding algorithm data as an object.
     *
     * <p>Such notifications will occur for a Fast Infoset SAX parser
     * when processing encoding algorithm data that is converted from an
     * array of byte to an object more suitable for processing.<p>
     *
     * @param URI the URI of the encoding algorithm
     * @param algorithm the encoding algorithm index
     * @param o the encoding algorithm object
     * @throws org.xml.sax.SAXException any SAX exception, possibly
     * wrapping another exception
     * @see com.sun.xml.fastinfoset.EncodingAlgorithmIndexes
     */
    void object(String URI, int algorithm, Object o) throws SAXException;
}


/*
 * Fast Infoset ver. 0.1 software ("Software")
 *
 * Copyright, 2004-2005 Sun Microsystems, Inc. All Rights Reserved.
 *
 * Software is licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. You may
 * obtain a copy of the License at:
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations.
 *
 * Sun supports and benefits from the global community of open source
 * developers, and thanks the community for its important contributions and
 * open standards-based technology, which Sun has adopted into many of its
 * products.
 *
 * Please note that portions of Software may be provided with notices and
 * open source licenses from such communities and third parties that govern the
 * use of those portions, and any licenses granted hereunder do not alter any
 * rights and obligations you may have under such open source licenses,
 * however, the disclaimer of warranty and limitation of liability provisions
 * in this License will apply to all Software in this distribution.
 *
 * You acknowledge that the Software is not designed, licensed or intended
 * for use in the design, construction, operation or maintenance of any nuclear
 * facility.
 *
 * Apache License
 * Version 2.0, January 2004
 * http://www.apache.org/licenses/
 *
 */

package com.sun.xml.fastinfoset.api.sax;

import org.xml.sax.SAXException;

/**
 * SAX2 extention handler to receive notification of character data as
 * primtive types.
 *
 * <p>This is an optional extension handler for SAX2. XML readers are not
 * required to recognize this handler, and it is not part of core-only
 * SAX2 distributions.</p>
 *
 * <p>This interface may be used with with a Fast Infoset
 * SAX parser to receive notification of data encoded using the
 * following built-in encoding algorithms specified in ITU-T Rec. X.891 | ISO/IEC 24824-1
 * (Fast Infoset), clause 10: "boolean", "base64", "short", "int", "long",
 * "float", "double" and "uuid" encoding algorithms.<p>
 *
 * <p>To set the PrimitiveTypeContentHandler for an XML reader, use the
 * {_at_link org.xml.sax.XMLReader#setProperty setProperty} method
 * with the property name
 * <code>URI TO BE DEFINED</code>
 * and an object implementing this interface (or null) as the value.
 * If the reader does not report primitive data types, it will throw a
 * {_at_link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException}</p>
 *
 * <p>To set the PrimitiveTypeContentHandler for an Fast Infoset reader, use
 * {_at_link com.sun.xml.fastinfoset.api.sax.FastInfosetReader#setPrimitiveTypeContentHandler
 * setPrimitiveTypeContentHandler} method.<p>

 * <p>The Parser will call methods of this interface to report each
 * chunk of character data that has been converted to an array of primitive
 * types, for example an array of integer or an array of float. Parsers may
 * return all contiguous primtive types in a single chunk, or they may split
 * it into several chunks</p>
 *
 * <p>The application must not attempt to read from the array
 * outside of the specified range.</p>
 * @version 0.1
 * @see com.sun.xml.fastinfoset.api.sax.EncodingAlgorithmContentHandler
 * @see com.sun.xml.fastinfoset.api.sax.FastInfosetReader
 * @see org.xml.sax.XMLReader
 */
public interface PrimitiveTypeContentHandler {
    /**
     * Receive notification of character data as an array of boolean.
     *
     * <p>The application must not attempt to read from the array
     * outside of the specified range.</p>
     *
     * <p>Such notifications will occur for a Fast Infoset SAX parser
     * when processing data encoded using the "boolean" encoding
     * algorithm, see subclause 10.7<p>.
     *
     * @param b the array of boolean
     * @param start the start position in the array
     * @param length the number of boolean to read from the array
     * @throws org.xml.sax.SAXException any SAX exception, possibly
     * wrapping another exception
     */
    void booleans(boolean [] b, int start, int length) throws SAXException;

    /**
     * Receive notification of character data as an array of byte.
     *
     * <p>The application must not attempt to read from the array
     * outside of the specified range.</p>
     *
     * <p>Such notifications will occur for a Fast Infoset SAX parser
     * when processing data encoded using the "base64" encoding
     * algorithm, see subclause 10.3.
     *
     * <p>Such a notification may occur for binary data that would
     * normally require base 64 encoding and reported as character data
     * using the {_at_link org.xml.sax.ContentHandler#characters characters}
     * method <p>.
     *
     * @param b the array of byte
     * @param start the start position in the array
     * @param length the number of byte to read from the array
     * @throws org.xml.sax.SAXException any SAX exception, possibly
     * wrapping another exception
     */
    void bytes(byte[] b, int start, int length) throws SAXException;
    
    /**
     * Receive notification of character data as an array of short.
     *
     * <p>The application must not attempt to read from the array
     * outside of the specified range.</p>
     *
     * <p>Such notifications will occur for a Fast Infoset SAX parser
     * when processing data encoded using the "short" encoding
     * algorithm, see subclause 10.4<p>.
     *
     * @param s the array of short
     * @param start the start position in the array
     * @param length the number of short to read from the array
     * @throws org.xml.sax.SAXException any SAX exception, possibly
     * wrapping another exception
     */
    void shorts(short[] s, int start, int length) throws SAXException;
    
    /**
     * Receive notification of character data as an array of int.
     *
     * <p>The application must not attempt to read from the array
     * outside of the specified range.</p>
     *
     * <p>Such notifications will occur for a Fast Infoset SAX parser
     * when processing data encoded using the "int" encoding
     * algorithm, see subclause 10.5<p>.
     *
     * @param i the array of int
     * @param start the start position in the array
     * @param length the number of int to read from the array
     * @throws org.xml.sax.SAXException any SAX exception, possibly
     * wrapping another exception
     */
    void ints(int [] i, int start, int length) throws SAXException;
    
    /**
     * Receive notification of character data as an array of long.
     *
     * <p>The application must not attempt to read from the array
     * outside of the specified range.</p>
     *
     * <p>Such notifications will occur for a Fast Infoset SAX parser
     * when processing data encoded using the "long" encoding
     * algorithm, see subclause 10.6<p>.
     *
     * @param l the array of long
     * @param start the start position in the array
     * @param length the number of long to read from the array
     * @throws org.xml.sax.SAXException any SAX exception, possibly
     * wrapping another exception
     */
    void longs(long [] l, int start, int length) throws SAXException;
    
    /**
     * Receive notification of character data as an array of float.
     *
     * <p>The application must not attempt to read from the array
     * outside of the specified range.</p>
     *
     * <p>Such notifications will occur for a Fast Infoset SAX parser
     * when processing data encoded using the "float" encoding
     * algorithm, see subclause 10.8<p>.
     *
     * @param f the array of float
     * @param start the start position in the array
     * @param length the number of float to read from the array
     * @throws org.xml.sax.SAXException any SAX exception, possibly
     * wrapping another exception
     */
    void floats(float [] f, int start, int length) throws SAXException;
    
    /**
     * Receive notification of character data as an array of double.
     *
     * <p>The application must not attempt to read from the array
     * outside of the specified range.</p>
     *
     * <p>Such notifications will occur for a Fast Infoset SAX parser
     * when processing data encoded using the "double" encoding
     * algorithm, see subclause 10.9<p>.
     *
     * @param d the array of double
     * @param start the start position in the array
     * @param length the number of double to read from the array
     * @throws org.xml.sax.SAXException any SAX exception, possibly
     * wrapping another exception
     */
    void doubles(double [] d, int start, int length) throws SAXException;

    /**
     * Receive notification of character data as an two array of UUID.
     *
     * <p>The application must not attempt to read from the array
     * outside of the specified range.</p>
     *
     * <p>Such notifications will occur for a Fast Infoset SAX parser
     * when processing data encoded using the "uuid" encoding
     * algorithm, see subclause 10.10<p>.
     *
     * @param msb the array of long of the most sigificant bits of
     * the UUIDs
     * @param lsb the array of long of the least sigificant bits of
     * the UUIDs
     * @param start the start position in the array
     * @param length the number of UUID to read from the array
     * @throws org.xml.sax.SAXException any SAX exception, possibly
     * wrapping another exception
     */
    void uuids(long[] msb, long[] lsb, int start, int length) throws SAXException;
}


/*
 * Fast Infoset ver. 0.1 software ("Software")
 *
 * Copyright, 2004-2005 Sun Microsystems, Inc. All Rights Reserved.
 *
 * Software is licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. You may
 * obtain a copy of the License at:
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations.
 *
 * Sun supports and benefits from the global community of open source
 * developers, and thanks the community for its important contributions and
 * open standards-based technology, which Sun has adopted into many of its
 * products.
 *
 * Please note that portions of Software may be provided with notices and
 * open source licenses from such communities and third parties that govern the
 * use of those portions, and any licenses granted hereunder do not alter any
 * rights and obligations you may have under such open source licenses,
 * however, the disclaimer of warranty and limitation of liability provisions
 * in this License will apply to all Software in this distribution.
 *
 * You acknowledge that the Software is not designed, licensed or intended
 * for use in the design, construction, operation or maintenance of any nuclear
 * facility.
 *
 * Apache License
 * Version 2.0, January 2004
 * http://www.apache.org/licenses/
 *
 */

package com.sun.xml.fastinfoset.api.sax;

import org.xml.sax.Attributes;


/**
 * Interface for a list of XML attributes that may contain encoding algorithm
 * data.
 *
 * @version 0.1
 * @see com.sun.xml.fastinfoset.api.sax.FastInfosetReader
 * @see org.xml.sax.XMLReader
 */
public interface EncodingAlgorithmAttributes extends Attributes {
    
    /**
     * Return the URI of the encoding algorithm.
     *
     * <p>If the encoding algorithm support is "None" then rull is returned.<p>
     *
     * <p> If "Generic" and "Primitive and application" then null is returned
     * if the encoding algorithm data is for a built-in encoding algorithm and
     * the URI is returned for an application defined encoding algorithm.<p>
     *
     * <p> If "Primitive" then null is returned.<p>
     *
     * @param index The attribute index (zero-based).
     * @return The URI.
     */
    public String getAlgorithmURI(int index);
 
    /**
     * Return the index of the encoding algorithm
     *
     * <p>If the encoding algorithm support is "None" then 0 is returned.<p>
     *
     * <p> If "Generic" and "Primitive and application" then the index of the
     * built-in or application defined encoding algorithm is returned.<p>
     *
     * <p> If "Primitive" then the index of the built-in encoding algorithm
     * is returned, otherwise 0 is returned.<p>
     *
     * @param index The attribute index (zero-based).
     * @return The index
     * @see com.sun.xml.fastinfoset.EncodingAlgorithmIndexes
     */
    public int getAlgorithmIndex(int index);
    
    /**
     * Return the data of the encoding algorithm.
     *
     * <p>If the encoding algorithm support is "None" then null is returned.<p>
     *
     * <p> If "Generic" then a byte[] object is returned for built-in and
     * application defined encoding algorithms.<p>
     *
     * <p> If "Primitive" then an object that is an array of the primitive type
     * is returned for a built-in encoding algorithm, otherwise null is
     * returned.<p>
     *
     * <p> If "Primitive and application" then an object that is an array of
     * the primitive type is returned for a built-in encoding algorithm and a
     * byte[] object is returned for application defined encoding algorithms.
     * <p>
     *
     * @param index The attribute index (zero-based).
     * @return The data
     * @see com.sun.xml.fastinfoset.EncodingAlgorithmIndexes
     */
    public Object getAlgorithmData(int index);
}



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe_at_fi.dev.java.net
For additional commands, e-mail: dev-help_at_fi.dev.java.net
© Oracle | By contributing to this project, you are agreeing to the terms of use described here.