net.sf.stax
Interface IdMapper

public interface IdMapper

An encapsulation of the process of mapping XML ids to java objects.

Ids can occur in an XML document before or after the point at which they are referenced. An IdMapper keeps track of the currently available mappings so that handlers can fix up object graphs as objects are bound to ids.

For example, given an xml document

 <?xml version="1.0" ?>
 <foo>
   <bar_ref id="0" />

   <bar id="0" />
   <bar id="1" />

   <bar_ref id="1" />
 <foo>
 

You can handle normal elements (bar) and reference elements (bar_ref) with

 class FooHandler
     extends StAXContentHandlerBase
 {
     private List results = new ArrayList();

     public void startElement(..., StAXDelegationContext dctx)
     {
         if ("bar".equals(qName))
         {
             dctx.delegate(barHandler);
         }
         else if ("bar_ref".equals(qName))
         {
             dctx.delegate(barRefHandler);
         }
     }

     class BarHandler
         extends StAXContentHandlerBase
     {
         private Bar bar;

         public void startTree(StAXContext ctx) { bar = new Bar(); }

         public void startElement(..., StAXDelegationContext dctx)
         {
             if ("bar".equals(qName))
             {
                 // ...
                 IdMapper mapper = dctx.getIdMapper();
                 mapper.registerItemForId(attrs.getValue("id"), bar);
             }
         }

         public void endElement(...)
         {
             if ("bar".equals(qName))
                 results.add(bar);
         }
     }

     class BarRefHandler
         extends StAXContentHandlerBase
     {
         private Bar bar;

         public void startElement(..., StAXDelegationContext dctx)
         {
             if ("bar".equals(qName))
             {
                 final String barRefId = attrs.getValue("id");

                 IdMapper mapper = dctx.getIdMapper();
                 mapper.addIdListener(new IdListener()
                     {
                         public void idRegistered(Object id, Object item)
                         {
                             if ((barRefId.equals(id)) && (item instanceof Bar))
                             {
                                 bar = (Bar) item;
                                 results.add(bar);
                             }
                         }
                     });
             }
         }
     }
 }
 

Version:

$Revision: 1.2 $ $Date: 2006/01/02 20:37:34 $

Author:

Matthew Pocock, Michael Heuer

Method Summary

void	addIdListener(IdListener listener) Add a listener for all ids.
void	addIdListener(IdListener listener, Object id) Add a listener for a specific id.
void	registerItemForId(Object id, Object item) Bind an id to an item.
void	removeIdListener(IdListener listener) Remove a listener for all ids.
void	removeIdListener(IdListener listener, Object id) Remove a listener for a specific id.

Method Detail

registerItemForId

void registerItemForId(Object id,
                       Object item)
                       throws SAXException

Bind an id to an item.

All listeners that have previously been registered for this id will be informed that the id is now bound. All future listeners will be informed that the id is bound before the stream stops parsing.

Parameters:

id - the id of the bound object

item - the item to register for this id

Throws:

SAXException - if the id has previously been bound

addIdListener

void addIdListener(IdListener listener)
                   throws SAXException

Add a listener for all ids.

The listener will be informed of all id events, past and future for the complete parse of the StAX stream. This may happen as each id is found, or all together after the whole StAX stream has been parsed.

Parameters:

listener - the IdListener to add

Throws:

SAXException - if the id has previously been bound

removeIdListener

void removeIdListener(IdListener listener)
                      throws SAXException

Remove a listener for all ids.

Parameters:

listener - the IdListener to remove

Throws:

SAXException - any SAX exception, possibly wrapping another exception

addIdListener

void addIdListener(IdListener listener,
                   Object id)
                   throws SAXException

Add a listener for a specific id.

The listener will be informed exactly once of an item associated with this id. This may happen on registration, as the id is bound, or after the whole StAX stream has been parsed.

Parameters:

listener - the IdListener to register

id - the that the listener is interested in

Throws:

SAXException - any SAX exception, possibly wrapping another exception

removeIdListener

void removeIdListener(IdListener listener,
                      Object id)
                      throws SAXException

Remove a listener for a specific id.

Parameters:

listener - the IdListener to remove

id - the id that the listener was interested in

Throws:

SAXException - any SAX exception, possibly wrapping another exception