<HTML>
<BODY>
The DD API has been developed in order to satisfy the requirement to access the web module deployment descriptor for other Netbeans modules in a simple and servlet spec.-independant way.
<h1>Overview of DD API</h1>
<h2>1. The Overall Architecture</h2>
<p>
The DD API is based on a bunch of interfaces based on the deployment descriptor xml structure. The names of interfaces correspond to the names of deployment descriptor elements in <b>web.xml</b> file.
The DD API interfaces are organized in a hierarchic tree structure where they are accassible through the root - <b>{@link org.netbeans.modules.j2ee.dd.api.web.WebApp}</b> - interface.
The implementation of DD API interfaces is hidden for clients. It is based on schema2beans infrastructure and is the DD version - specific. (there is always requirement to support at least two successive versions of DD specification).
The root of the deployment descriptor is accessible through the <b>{@link org.netbeans.modules.j2ee.dd.api.web.DDProvider}</b> class.
</p>
<h2>2. What it is not.</h2>
<p>
The DD API provides no UI for deployment descriptor editing.
</p>
<i><b>Comments : </b></i>
<spanstyle="color:800040">[*]</span> - objects occur multiple times in parent object (0-n)
<spanstyle="color:800040">[+]</span> - objects occur multiple times in parent object (1-n)
<spanstyle="color:800040">[?]</span> - object can occur only once in parent object (0-1)
</pre>
<h2>4. The structure of method names.</h2>
<p>
The syntax and usage of interfaces methods is very simple and straightforward.<br>
If certain object [of XYZ interface] occurs multiple times in parent object these methods are present in parent interface :
<ul>
<li> <b>XYZ [] getXYZ</b> (); - returns an array of XYZ objects</li>
<li> <b>XYZ getXYZ</b> (int i); -returns an XYZ object at the certain position (i) within the array</li>
<li> <b>void setXYZ</b> (XYZ[] array); - sets the array of XYZ objects</li>
<li> <b>void setXYZ</b> (int i, XYZ object); - sets the XYZ object at certain position (i)</li>
<li> <b>int addXYZ</b> (XYZ object); - adds the XYZ object to the parent object</li>
<li> <b>int removeXYZ</b> (XYZ object); - removes the XYZ object from the parent object</li>
<li> <b>int sizeXYZ</b> (); - returns the size of XYZ array</li>
</ul><br>
If certain object [of XYZ interface] can occur only once in parent object these methods are present in parent interface :
<ul>
<li> <b>XYZ getSingleXYZ</b> (); - returns an XYZ object or null</li>
<li> <b>void setXYZ</b> (XYZ object); - sets the XYZ object to the parent object</li>
</ul><br>
Example : The {@link org.netbeans.modules.j2ee.dd.api.web.WebApp} interface contains these methods for getting/setting {@link org.netbeans.modules.j2ee.dd.api.web.Servlet}s and {@link org.netbeans.modules.j2ee.dd.api.web.WelcomeFileList} :
<ul>
<li> {@link org.netbeans.modules.j2ee.dd.api.web.Servlet} [] <b>getServlet</b> ();</li>
<li> {@link org.netbeans.modules.j2ee.dd.api.web.Servlet} <b>getServlet</b> (int i);</li>
<li> void <b>setServlet</b> ({@link org.netbeans.modules.j2ee.dd.api.web.Servlet}[] servlets);</li>
<li> void <b>setServlet</b> (int i, {@link org.netbeans.modules.j2ee.dd.api.web.Servlet} servlet);</li>
<li> int <b>addServlet</b> ({@link org.netbeans.modules.j2ee.dd.api.web.Servlet}servlet);</li>
<li> int <b>removeServlet</b> ({@link org.netbeans.modules.j2ee.dd.api.web.Servlet} servlet);</li>
<li> int <b>sizeServlet</b> ();</li>
<li> {@link org.netbeans.modules.j2ee.dd.api.web.WelcomeFileList} <b>getSingleWelcomeFileList</b> ();</li>
<li> void <b>setWelcomeFileList</b> ({@link org.netbeans.modules.j2ee.dd.api.web.WelcomeFileList} list);</li>
</ul><br>
Interfaces contain additional methods corresponding to the simple(String) properties following the deployment descriptor xml syntax.<br>
Example : The {@link org.netbeans.modules.j2ee.dd.api.web.Taglib} interface contains these additional getters/setters :
<ul>
<li> String <b>getTaglibUri</b> ();</li>
<li> String <b>getTaglibLocation</b> ();</li>
<li> void <b>setTaglibUri</b> (String uri);</li>
<li> void <b>setTaglibLocation</b> (String location);</li>
</ul><br>
Interfaces usually extends some interfaces from the <b>{@link org.netbeans.modules.j2ee.dd.api.common}</b> package. For example if aDD element has the description property, it extends the {@link org.netbeans.modules.j2ee.dd.api.common.DescriptionInterface} containing the methods for description property handling.<br>
Example : The {@link org.netbeans.modules.j2ee.dd.api.web.WebApp}, {@link org.netbeans.modules.j2ee.dd.api.web.Servlet}, {@link org.netbeans.modules.j2ee.dd.api.web.Filter}, {@link org.netbeans.modules.j2ee.dd.api.web.Listener}, {@link org.netbeans.modules.j2ee.dd.api.common.ServiceRef}, {@link org.netbeans.modules.j2ee.dd.api.web.WebResourceCollection} interfaces have the additional functionality for description proprty.
<h2>5. DDProvider class - getting the root interface from web.xml file.</h2>
Package: <b>{@link org.netbeans.modules.j2ee.dd.api.web}</b>
<p>
Provides the access to the deployment descriptor root - {@link org.netbeans.modules.j2ee.dd.api.web.WebApp} - object.
The {@link org.netbeans.modules.j2ee.dd.api.web.DDProvider} class is a singleton and caches the WebApp objects in IDE.<br>
There are following methods for accessing {@link org.netbeans.modules.j2ee.dd.api.web.WebApp} object in DDProvider : <br>
<ul>
<li>{@link org.netbeans.modules.j2ee.dd.api.web.DDProvider#getDDRoot(org.openide.filesystems.FileObject)};</li>
<li>{@link org.netbeans.modules.j2ee.dd.api.web.DDProvider#getDDRoot(java.io.File)};</li>
</ul>
<h2>6. Deployment descriptor modification.</h2>
<p> DD API enables the full modification of deployment descriptor elements including:
<ul>
<li>adding new elements</li>
<li>removing elements</li>
<li>changing the value of elements</li>
</ul>
<p>
See the <b><a href="arch/usage.html">Examples of usage</a></b>.
</p>
<h2>7. Writing changes.</h2>
<p>
The modificated {@link org.netbeans.modules.j2ee.dd.api.web.WebApp} object can be serialized to FileObject using :
<ul>
<li>void write({@link org.openide.filesystems.FileObject} fo) throws {@link java.io.IOException};</li>
</ul>
<p>
There is also another <b>write</b> mathod available on any interface to serialize the fraction of deployment descriptor to OutputStream :
<ul>
<li>void write({@link java.io.OutputStream} os) throws {@link java.io.IOException};</li>
</ul>
<p>
See the <b><a href="arch/usage.html">Examples of usage</a></b>.
</p>
<hr>
<p>
See also :
<ul>
<li><a href="architecture-summary.html">Architecture Summary</a></li>
<li><a href="apichanges.html">API Changes</a></li>
<li><a href="arch/ddapi_architecture.html">Original Architecture Document for the Web part of DD API</a></li>
</ul>
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung und die Messung sind noch experimentell.
