~~ Licensed to the Apache Software Foundation (ASF) under one or more
~~ contributor license agreements.  See the NOTICE file distributed with
~~ this work for additional information regarding copyright ownership.
~~ The ASF licenses this file to You 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 under the License.

 ---
 Pluto Descriptor Service Implementation
 ---
 Elliot Metsger
 ---
 June 1, 2006

Pluto Descriptor Service Implementation

    The Pluto descriptor services provide an entry point for reading and 
writing object models representing the web and portlet descriptor files
(<<<WEB-INF/web.xml>>> and <<<WEB-INF/portlet.xml>>>).  The implementation 
uses {{{http://www.castor.org}Castor}} for marshalling and unmarshalling
the object models.

    If you use the Pluto descriptor services in your own project, be
sure to code to the interfaces <<<org.apache.pluto.descriptors.services.PortletAppDescriptorService>>>
and <<<org.apache.pluto.descriptors.services.WebAppDescriptorService>>> and 
not directly to the implementation classes.  The purpose of this documentation
is to detail which XML parser the descriptor service implementation uses.

*--------------+--------------------------------------+
|Pluto Version |org.apache.pluto.useJaxp default value|
*--------------+--------------------------------------+
|1.2.x         |true                                  |
*--------------+--------------------------------------+
|1.1.4+        |false                                 |
*--------------+--------------------------------------+
Default value of the <<<org.apache.pluto.useJaxp>>> system property

* XML parsing in Pluto 1.2.x

    In Pluto 1.2.x, Castor uses {{{http://java.sun.com/webservices/jaxp/}JAXP API}}
and the default JDK 1.5 XML parser for (un)marshalling the descriptor files.  Note
that JDK 1.5 or greater is required to run Pluto 1.2.x.  This eliminates the need
for Pluto to have an XML parser in a shared classloader.  

    If for some reason you need to disable the use of JAXP, set the system property 
<<<org.apache.pluto.useJaxp>>> to the string <<<false>>>.  When the property is 
set to <<<false>>>, Castor will use the parser defined by the 
<<<org.exolab.castor.parser>>> property.  You will be responsible for providing 
the XML parser APIs and implementation libraries.

* XML parsing in Pluto 1.1.4 and up

    If you use Pluto 1.1.4 or greater (but still within the 1.1 line), Castor will 
use the Xerces parser distributed with Pluto, to maintain JDK 1.4 compatibility.  
However, if you run Pluto 1.1.4 under JDK 1.5, you can enable JAXP by setting the 
system property <<<org.apache.pluto.useJaxp>>> equal to the string <<<true>>>.  In
this case, the parser that was defined by the Castor property <<<org.exolab.castor.parser>>>
will be overridden.