org.exolab.javasource.JDocComment Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of castor-codegen Show documentation
The newest version!
/**
 * Redistribution and use of this software and associated documentation ("Software"), with or
 * without modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain copyright statements and notices. Redistributions
 * must also contain a copy of this document.
 *
 * 2. Redistributions in binary form must reproduce the above copyright notice, this list of
 * conditions and the following disclaimer in the documentation and/or other materials provided with
 * the distribution.
 *
 * 3. The name "Exolab" must not be used to endorse or promote products derived from this Software
 * without prior written permission of Intalio, Inc. For written permission, please contact
 * [email protected].
 *
 * 4. Products derived from this Software may not be called "Exolab" nor may "Exolab" appear in
 * their names without prior written permission of Intalio, Inc. Exolab is a registered trademark of
 * Intalio, Inc.
 *
 * 5. Due credit should be given to the Exolab Project (http://www.exolab.org/).
 *
 * THIS SOFTWARE IS PROVIDED BY INTALIO, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESSED OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTALIO, INC. OR ITS
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
 * WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * Copyright 1999-2003 (C) Intalio, Inc. All Rights Reserved.
 */
package org.exolab.javasource;

import java.util.Enumeration;
import java.util.Vector;

/**
 * A class that "SOMEWHAT" represents a JavaDoc Comment.
 *
 * @author Keith Visco
 * @version $Revision$ $Date: 2005-02-26 17:30:28 -0700 (Sat, 26 Feb 2005) $
 */
public final class JDocComment {

  /** An ordered list of descriptors. */
  private final Vector _descriptors = new Vector();

  /** The internal buffer for this JDocComment. */
  private final StringBuffer _comment = new StringBuffer();


  /**
   * Creates a new JavaDoc Comment.
   */
  public JDocComment() {
    super();
  }

  /**
   * Creates a new JavaDoc Comment and initializie it with given JDocDescriptor.
   * 
   * @param jdesc The JDocDescriptor to add.
   */
  public JDocComment(final JDocDescriptor jdesc) {
    this();
    addDescriptor(jdesc);
  }

  /**
   * Adds the given JDocDescriptor to this JDocComment.
   *
   * @param jdesc The JDocDescriptor to add.
   */
  public void addDescriptor(final JDocDescriptor jdesc) {
    if (jdesc == null) {
      return;
    }
    // -- on the fly sorting of descriptors
    if (_descriptors.isEmpty()) {
      _descriptors.add(jdesc);
      return;
    }

    for (int i = 0; i < _descriptors.size(); i++) {
      JDocDescriptor jdd = _descriptors.elementAt(i);

      short compare = jdesc.compareTo(jdd);

      switch (compare) {
        case 0: // equal
          _descriptors.insertElementAt(jdesc, i + 1);
          return;
        case -1: // -- less than
          _descriptors.insertElementAt(jdesc, i);
          return;
        default:
          // -- keep looking
          break;
      }
    }

    // -- if we make it here we need to add
    _descriptors.addElement(jdesc);
  }

  /**
   * Appends the provided comment String to this JDocComment.
   *
   * @param comment The comment to append.
   */
  public void appendComment(final String comment) {
    _comment.append(comment);
  }

  /**
   * Returns the String value of this JDocComment.
   *
   * @return The String value of this JDocComment.
   */
  public String getComment() {
    return _comment.toString();
  }

  /**
   * Sets the comment String of this JDocComment.
   *
   * @param comment The comment String of this JDocComment.
   */
  public void setComment(final String comment) {
    _comment.setLength(0);
    _comment.append(comment);
  }

  /**
   * Returns an Enumeration of the parameters of this JDocComment.
   *
   * @return An Enumeration of the parameters of this JDocComment.
   */
  public Enumeration getDescriptors() {
    return _descriptors.elements();
  }

  /**
   * Returns the length of the JavaDoc comment in characters.
   *
   * @return The length of the JavaDoc comment in characters.
   */
  public int getLength() {
    return _comment.length();
  }

  /**
   * Returns the Parameter Descriptor associated with the given name.
   *
   * @param name The name whose ParamDescriptor is being searched for.
   * @return the Parameter Descriptor associated with the given name.
   */
  public JDocDescriptor getParamDescriptor(final String name) {
    if (name == null) {
      return null;
    }

    for (JDocDescriptor jdd : _descriptors) {
      if (jdd.getType() == JDocDescriptor.PARAM) {
        if (name.equals(jdd.getName())) {
          return jdd;
        }
      }
    }
    return null;
  }


  /**
   * Prints this JavaDoc comment using the given JSourceWriter.
   *
   * @param jsw The JSourceWriter to print to.
   */
  public void print(final JSourceWriter jsw) {
    // -- I reuse JComment for printing
    JComment jComment = new JComment(JComment.JAVADOC_STYLE);

    jComment.setComment(_comment.toString());

    // -- force a separating "*" for readability
    if (!_descriptors.isEmpty()) {
      jComment.appendComment("\n");
    }

    for (JDocDescriptor jdd : _descriptors) {
      jComment.appendComment("\n");
      jComment.appendComment(jdd.toString());
    }
    jComment.print(jsw);
  }

  public String toString() {
    return "/**\n" + " * " + " */\n";
  }

}