IPlanetDeploymentTool (Apache Ant API)
Description: declaration: package: org.apache.tools.ant.taskdefs.optional.ejb, class: IPlanetDeploymentTool

# Class IPlanetDeploymentTool

java.lang.Object
org.apache.tools.ant.taskdefs.optional.ejb.GenericDeploymentTool
org.apache.tools.ant.taskdefs.optional.ejb.IPlanetDeploymentTool

All Implemented Interfaces:
  `EJBDeploymentTool`

public class IPlanetDeploymentTool extends GenericDeploymentTool
This class is used to generate iPlanet Application Server (iAS) 6.0 stubs and skeletons and build an EJB Jar file. It is designed to be used with the Ant `ejbjar` task. If only stubs and skeletons need to be generated (in other words, if no JAR file needs to be created), refer to the `iplanet-ejbc` task and the `IPlanetEjbcTask` class.

The following attributes may be specified by the user:

- destdir -- The base directory into which the generated JAR files will be written. Each JAR file is written in directories which correspond to their location within the "descriptordir" namespace. This is a required attribute.
- classpath -- The classpath used when generating EJB stubs and skeletons. This is an optional attribute (if omitted, the classpath specified in the "ejbjar" parent task will be used). If specified, the classpath elements will be prepended to the classpath specified in the parent "ejbjar" task. Note that nested "classpath" elements may also be used.
- keepgenerated -- Indicates whether or not the Java source files which are generated by ejbc will be saved or automatically deleted. If "yes", the source files will be retained. This is an optional attribute (if omitted, it defaults to "no").
- debug -- Indicates whether or not the ejbc utility should log additional debugging statements to the standard output. If "yes", the additional debugging statements will be generated (if omitted, it defaults to "no").
- iashome -- May be used to specify the "home" directory for this iPlanet Application server installation. This is used to find the ejbc utility if it isn't included in the user's system path. This is an optional attribute (if specified, it should refer to the `[install-location]/iplanet/ias6/ias` directory). If omitted, the ejbc utility must be on the user's system path.
- suffix -- String value appended to the JAR filename when creating each JAR. This attribute is not required (if omitted, it defaults to ".jar").

For each EJB descriptor found in the "ejbjar" parent task, this deployment tool will locate the three classes that comprise the EJB. If these class files cannot be located in the specified `srcdir` directory, the task will fail. The task will also attempt to locate the EJB stubs and skeletons in this directory. If found, the timestamps on the stubs and skeletons will be checked to ensure they are up to date. Only if these files cannot be found or if they are out of date will ejbc be called.

See Also:
  - `IPlanetEjbc`

- ## Field Summary

  ### Fields inherited from class GenericDeploymentTool

  `ANALYZER_CLASS_FULL, ANALYZER_CLASS_SUPER, ANALYZER_FULL, ANALYZER_NONE, ANALYZER_SUPER, DEFAULT_ANALYZER, DEFAULT_BUFFER_SIZE, EJB_DD, JAR_COMPRESS_LEVEL, MANIFEST, META_DIR`
  Modifier and Type
  Field
  Description
  `static final String`
  `ANALYZER_CLASS_FULL`
  The analyzer class for the super analyzer
  `static final String`
  `ANALYZER_CLASS_SUPER`
  The analyzer class for the super analyzer
  `static final String`
  `ANALYZER_FULL`
  A dependency analyzer name to find all related classes
  `static final String`
  `ANALYZER_NONE`
  A dependency analyzer name for no analyzer
  `static final String`
  `ANALYZER_SUPER`
  A dependency analyzer name to find ancestor classes
  `static final String`
  `DEFAULT_ANALYZER`
  The default analyzer
  `static final int`
  `DEFAULT_BUFFER_SIZE`
  The default buffer byte size to use for IO
  `protected static final String`
  `EJB_DD`
  Name for EJB Deployment descriptor within EJB jars
  `static final int`
  `JAR_COMPRESS_LEVEL`
  The level to use for compression
  `protected static final String`
  `MANIFEST`
  The standard MANIFEST file
  `protected static final String`
  `META_DIR`
  The standard META-INF directory in jar files

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `IPlanetDeploymentTool()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `addVendorFiles(Hashtable<String,File> ejbFiles, String ddPrefix)`
  Add the iAS-specific EJB descriptor to the list of files which will be written to the JAR file.
  `protected void`
  `checkConfiguration(String descriptorFileName, SAXParser saxParser)`
  Verifies that the user selections are valid.
  `protected String`
  `getPublicId()`
  The iAS ejbc utility doesn't require the Public ID of the descriptor's DTD for it to process correctly--this method always returns `null` .
  `protected Hashtable<String,File>`
  `parseEjbFiles(String descriptorFileName, SAXParser saxParser)`
  This method returns a list of EJB files found when the specified EJB descriptor is parsed and processed.
  `void`
  `processDescriptor(String descriptorName, SAXParser saxParser)`
  Process a deployment descriptor, generating the necessary vendor specific deployment files.
  `void`
  `setDebug(boolean debug)`
  Sets whether or not debugging output will be generated when ejbc is executed.
  `void`
  `setGenericJarSuffix(String inString)`
  Since iAS doesn't generate a "generic" JAR as part of its processing, this attribute is ignored and a warning message is displayed to the user.
  `void`
  `setIashome(File iashome)`
  Setter method used to store the "home" directory of the user's iAS installation.
  `void`
  `setKeepgenerated(boolean keepgenerated)`
  Setter method used to specify whether the Java source files generated by the ejbc utility should be saved or automatically deleted.
  `void`
  `setSuffix(String jarSuffix)`
  Setter method used to specify the filename suffix (for example, ".jar") for the JAR files to be created.

  ### Methods inherited from class GenericDeploymentTool

  `addFileToJar, addSupportClasses, checkAndAddDependants, configure, createClasspath, getClassLoaderForBuild, getCombinedClasspath, getConfig, getDescriptorHandler, getDestDir, getJarBaseName, getLocation, getManifestFile, getTask, getVendorDDPrefix, log, needToRebuild, registerKnownDTDs, setClasspath, setDestdir, setTask, usingBaseJarName, validateConfigured, writeJar`
  Modifier and Type
  Method
  Description
  `protected void`
  `addFileToJar(JarOutputStream jStream, File inputFile, String logicalFilename)`
  Utility method that encapsulates the logic of adding a file entry to a .jar file.
  `protected void`
  `addSupportClasses(Hashtable<String,File> ejbFiles)`
  Adds any classes the user specifies using support nested elements to the `ejbFiles` Hashtable.
  `protected void`
  `checkAndAddDependants(Hashtable<String,File> checkEntries)`
  Add all available classes, that depend on Remote, Home, Bean, PK
  `void`
  `configure(org.apache.tools.ant.taskdefs.optional.ejb.EjbJar.Config config)`
  Configure this tool for use in the ejbjar task.
  `Path`
  `createClasspath()`
  Add the classpath for the user classes
  `protected ClassLoader`
  `getClassLoaderForBuild()`
  Returns a Classloader object which parses the passed in generic EjbJar classpath.
  `protected Path`
  `getCombinedClasspath()`
  Get the classpath by combining the one from the surrounding task, if any and the one from this tool.
  `protected org.apache.tools.ant.taskdefs.optional.ejb.EjbJar.Config`
  `getConfig()`
  Get the basename terminator.
  `protected DescriptorHandler`
  `getDescriptorHandler(File srcDir)`
  Get a descriptionHandler.
  `protected File`
  `getDestDir()`
  Get the destination directory.
  `protected String`
  `getJarBaseName(String descriptorFileName)`
  Using the EJB descriptor file name passed from the `ejbjar` task, this method returns the "basename" which will be used to name the completed JAR file.
  `protected Location`
  `getLocation()`
  Get the build file location associated with this element's task.
  `protected File`
  `getManifestFile(String prefix)`
  Get the manifest file to use for building the generic jar.
  `protected Task`
  `getTask()`
  Get the task for this tool.
  `String`
  `getVendorDDPrefix(String baseName, String descriptorFileName)`
  Get the prefix for vendor deployment descriptors.
  `protected void`
  `log(String message, int level)`
  Log a message to the Ant output.
  `protected boolean`
  `needToRebuild(Hashtable<String,File> ejbFiles, File jarFile)`
  This method checks the timestamp on each file listed in the `ejbFiles` and compares them to the timestamp on the `jarFile` .
  `protected void`
  `registerKnownDTDs(DescriptorHandler handler)`
  Register the locations of all known DTDs.
  `void`
  `setClasspath(Path classpath)`
  Set the classpath to be used for this compilation.
  `void`
  `setDestdir(File inDir)`
  Set the destination directory; required.
  `void`
  `setTask(Task task)`
  Set the task which owns this tool
  `protected boolean`
  `usingBaseJarName()`
  Indicate if this build is using the base jar name.
  `void`
  `validateConfigured()`
  Called to validate that the tool parameters have been configured.
  `protected void`
  `writeJar(String baseName, File jarfile, Hashtable<String,File> files, String publicId)`
  Method used to encapsulate the writing of the JAR file.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### IPlanetDeploymentTool

    public IPlanetDeploymentTool()

- ## Method Details

  - ### setIashome

    public void setIashome(File iashome)
    Setter method used to store the "home" directory of the user's iAS installation. The directory specified should typically be `[install-location]/iplanet/ias6/ias`.
    Parameters:
      `iashome` - The home directory for the user's iAS installation.

  - ### setKeepgenerated

    public void setKeepgenerated(boolean keepgenerated)
    Setter method used to specify whether the Java source files generated by the ejbc utility should be saved or automatically deleted.
    Parameters:
      `keepgenerated` - boolean which, if `true`, indicates that Java source files generated by ejbc for the stubs and skeletons should be kept.

  - ### setDebug

    public void setDebug(boolean debug)
    Sets whether or not debugging output will be generated when ejbc is executed.
    Parameters:
      `debug` - A boolean indicating if debugging output should be generated

  - ### setSuffix

    public void setSuffix(String jarSuffix)
    Setter method used to specify the filename suffix (for example, ".jar") for the JAR files to be created.
    Parameters:
      `jarSuffix` - The string to use as the JAR filename suffix.

  - ### setGenericJarSuffix

    public void setGenericJarSuffix(String inString)
    Since iAS doesn't generate a "generic" JAR as part of its processing, this attribute is ignored and a warning message is displayed to the user.
    Overrides:
      `setGenericJarSuffix` in class `GenericDeploymentTool`
    Parameters:
      `inString` - the string to use as the suffix. This parameter is ignored.

  - ### processDescriptor

    public void processDescriptor(String descriptorName, SAXParser saxParser)
    Process a deployment descriptor, generating the necessary vendor specific deployment files...
    Specified by:
      `processDescriptor` in interface `EJBDeploymentTool`
    Overrides:
      `processDescriptor` in class `GenericDeploymentTool`
    Parameters:
      `descriptorName` - the name of the deployment descriptor
      `saxParser` - a SAX parser which can be used to parse the deployment descriptor.

  - ### checkConfiguration

    protected void checkConfiguration(String descriptorFileName, SAXParser saxParser) throws BuildException
    Verifies that the user selections are valid.
    Overrides:
      `checkConfiguration` in class `GenericDeploymentTool`
    Parameters:
      `descriptorFileName` - String representing the file name of an EJB descriptor to be processed
      `saxParser` - SAXParser which may be used to parse the XML descriptor
    Throws:
      `BuildException` - If the user selections are invalid.

  - ### parseEjbFiles

    protected Hashtable<String,File> parseEjbFiles(String descriptorFileName, SAXParser saxParser) throws IOException, SAXException
    This method returns a list of EJB files found when the specified EJB descriptor is parsed and processed.
    Overrides:
      `parseEjbFiles` in class `GenericDeploymentTool`
    Parameters:
      `descriptorFileName` - String representing the file name of an EJB descriptor to be processed
      `saxParser` - SAXParser which may be used to parse the XML descriptor
    Returns:
      Hashtable of EJB class (and other) files to be added to the completed JAR file
    Throws:
      `IOException` - An IOException from the parser, possibly from the byte stream or character stream
      `SAXException` - Any SAX exception, possibly wrapping another exception

  - ### addVendorFiles

    protected void addVendorFiles(Hashtable<String,File> ejbFiles, String ddPrefix)
    Add the iAS-specific EJB descriptor to the list of files which will be written to the JAR file.
    Overrides:
      `addVendorFiles` in class `GenericDeploymentTool`
    Parameters:
      `ejbFiles` - Hashtable of EJB class (and other) files to be added to the completed JAR file.
      `ddPrefix` - not used

  - ### getPublicId

    protected String getPublicId()
    The iAS ejbc utility doesn't require the Public ID of the descriptor's DTD for it to process correctly--this method always returns `null` .
    Overrides:
      `getPublicId` in class `GenericDeploymentTool`
    Returns:
      `null`.