jakarta-taglibs-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jstrac...@apache.org
Subject cvs commit: jakarta-taglibs/src/doc guidelines.xml project.xml
Date Tue, 22 May 2001 16:34:35 GMT
jstrachan    01/05/22 09:34:32

  Modified:    src/doc  project.xml
  Added:       src/doc  guidelines.xml
  Log:
  Added Shawn's developer guidelines to website
  
  Revision  Changes    Path
  1.13      +61 -60    jakarta-taglibs/src/doc/project.xml
  
  Index: project.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-taglibs/src/doc/project.xml,v
  retrieving revision 1.12
  retrieving revision 1.13
  diff -u -r1.12 -r1.13
  --- project.xml	2001/05/21 23:04:08	1.12
  +++ project.xml	2001/05/22 16:34:17	1.13
  @@ -1,60 +1,61 @@
  -<?xml version="1.0" encoding="ISO-8859-1"?>
  -<project name="Taglibs Framework"
  -         href="http://jakarta.apache.org/taglibs"
  -        image="images/taglibs.gif">
  -
  -  <title>Jakarta-Taglib Downloads</title>
  -
  -    <menu name="Downloads">
  -      <item name="Entire Binary Distribution" href="http://jakarta.apache.org/builds/jakarta-taglibs/nightly"/>
  -      <item name="Entire Source Distribution" href="http://jakarta.apache.org/builds/jakarta-taglibs/nightly/src"/>
  -      <item name="Documentation" href="http://jakarta.apache.org/builds/jakarta-taglibs/nightly/projects/doc"/>
  -    </menu>
  -
  -    <menu name="Individual Tag Libraries">
  -      <item name="Application Taglib" href="http://jakarta.apache.org/taglibs/doc/application-doc/intro.html"/>
  -      <item name="BSF Taglib"      href="http://jakarta.apache.org/taglibs/doc/bsf-doc/intro.html"/>
  -      <item name="DateTime Taglib" href="http://jakarta.apache.org/taglibs/doc/datetime-doc/intro.html"/>
  -      <item name="DBTags Taglib"     href="http://jakarta.apache.org/taglibs/doc/dbtags-doc/intro.html"/>
  -      <item name="I18N Taglib"     href="http://jakarta.apache.org/taglibs/doc/i18n-doc/intro.html"/>
  -      <item name="Input Taglib"    href="http://jakarta.apache.org/taglibs/doc/input-doc/intro.html"/>
  -      <item name="IO Taglib"       href="http://jakarta.apache.org/taglibs/doc/io-doc/intro.html"/>
  -      <item name="JNDI Taglib"     href="http://jakarta.apache.org/taglibs/doc/jndi-doc/intro.html"/>
  -      <item name="JSP Spec Taglib" href="http://jakarta.apache.org/taglibs/doc/jspspec-doc/intro.html"/>
  -      <item name="Log Taglib"      href="http://jakarta.apache.org/taglibs/doc/log-doc/intro.html"/>
  -      <item name="Mailer Taglib"   href="http://jakarta.apache.org/taglibs/doc/mailer-doc/intro.html"/>
  -      <item name="Page Taglib"     href="http://jakarta.apache.org/taglibs/doc/page-doc/intro.html"/>
  -      <item name="Random Taglib"   href="http://jakarta.apache.org/taglibs/doc/random-doc/intro.html"/>
  -      <item name="Regexp Taglib"   href="http://jakarta.apache.org/taglibs/doc/regexp-doc/intro.html"/>
  -      <item name="Request Taglib"  href="http://jakarta.apache.org/taglibs/doc/request-doc/intro.html"/>
  -      <item name="Response Taglib" href="http://jakarta.apache.org/taglibs/doc/response-doc/intro.html"/>
  -      <item name="Scrape Taglib"   href="http://jakarta.apache.org/taglibs/doc/scrape-doc/intro.html"/>
  -      <item name="Session Taglib"  href="http://jakarta.apache.org/taglibs/doc/session-doc/intro.html"/>
  -      <item name="Utility Taglib"  href="http://jakarta.apache.org/taglibs/doc/utility-doc/intro.html"/>
  -      <item name="XSL Taglib"      href="http://jakarta.apache.org/taglibs/doc/xsl-doc/intro.html"/>
  -      <item name="XTags Taglib"    href="http://jakarta.apache.org/taglibs/doc/xtags-doc/intro.html"/>
  -    </menu>
  -    
  -    <menu name="Unsupported Tag Libraries">
  -      <item name="SQL Sample Taglib"      href="http://jakarta.apache.org/taglibs/doc/sql-doc/intro.html"/>
  -    </menu>
  -    
  -    <menu name="Custom Tag Library Extensions">
  -      <item name="UltraDev 4.0" href="http://jakarta.apache.org/taglibs/doc/ultradev4/intro.html"/>
  -    </menu>
  -
  -    <menu name="Documentation">
  -      <item name="Binary Dist" href="binarydist.html"/>
  -      <item name="Source Dist" href="sourcedist.html"/>
  -      <item name="Tutorial" href="tutorial.html"/>
  -    </menu>
  -
  -    <menu name="Getting Involved">
  -      <item name="Overview" href="http://jakarta.apache.org/site/getinvolved.html"/>
  -      <item name="CVS Repositories" href="http://jakarta.apache.org/site/cvsindex.html"/>
  -      <item name="Mailing Lists" href="http://jakarta.apache.org/site/mail.html"/>
  -      <item name="Reference Library" href="http://jakarta.apache.org/site/library.html"/>
  -      <item name="Bug Database" href="http://jakarta.apache.org/site/bugs.html"/>
  -    </menu>
  -
  -</project>
  +<?xml version="1.0" encoding="ISO-8859-1"?>
  +<project name="Taglibs Framework"
  +         href="http://jakarta.apache.org/taglibs"
  +        image="images/taglibs.gif">
  +
  +  <title>Jakarta-Taglib Downloads</title>
  +
  +    <menu name="Downloads">
  +      <item name="Entire Binary Distribution" href="http://jakarta.apache.org/builds/jakarta-taglibs/nightly"/>
  +      <item name="Entire Source Distribution" href="http://jakarta.apache.org/builds/jakarta-taglibs/nightly/src"/>
  +      <item name="Documentation" href="http://jakarta.apache.org/builds/jakarta-taglibs/nightly/projects/doc"/>
  +    </menu>
  +
  +    <menu name="Individual Tag Libraries">
  +      <item name="Application Taglib" href="http://jakarta.apache.org/taglibs/doc/application-doc/intro.html"/>
  +      <item name="BSF Taglib"      href="http://jakarta.apache.org/taglibs/doc/bsf-doc/intro.html"/>
  +      <item name="DateTime Taglib" href="http://jakarta.apache.org/taglibs/doc/datetime-doc/intro.html"/>
  +      <item name="DBTags Taglib"     href="http://jakarta.apache.org/taglibs/doc/dbtags-doc/intro.html"/>
  +      <item name="I18N Taglib"     href="http://jakarta.apache.org/taglibs/doc/i18n-doc/intro.html"/>
  +      <item name="Input Taglib"    href="http://jakarta.apache.org/taglibs/doc/input-doc/intro.html"/>
  +      <item name="IO Taglib"       href="http://jakarta.apache.org/taglibs/doc/io-doc/intro.html"/>
  +      <item name="JNDI Taglib"     href="http://jakarta.apache.org/taglibs/doc/jndi-doc/intro.html"/>
  +      <item name="JSP Spec Taglib" href="http://jakarta.apache.org/taglibs/doc/jspspec-doc/intro.html"/>
  +      <item name="Log Taglib"      href="http://jakarta.apache.org/taglibs/doc/log-doc/intro.html"/>
  +      <item name="Mailer Taglib"   href="http://jakarta.apache.org/taglibs/doc/mailer-doc/intro.html"/>
  +      <item name="Page Taglib"     href="http://jakarta.apache.org/taglibs/doc/page-doc/intro.html"/>
  +      <item name="Random Taglib"   href="http://jakarta.apache.org/taglibs/doc/random-doc/intro.html"/>
  +      <item name="Regexp Taglib"   href="http://jakarta.apache.org/taglibs/doc/regexp-doc/intro.html"/>
  +      <item name="Request Taglib"  href="http://jakarta.apache.org/taglibs/doc/request-doc/intro.html"/>
  +      <item name="Response Taglib" href="http://jakarta.apache.org/taglibs/doc/response-doc/intro.html"/>
  +      <item name="Scrape Taglib"   href="http://jakarta.apache.org/taglibs/doc/scrape-doc/intro.html"/>
  +      <item name="Session Taglib"  href="http://jakarta.apache.org/taglibs/doc/session-doc/intro.html"/>
  +      <item name="Utility Taglib"  href="http://jakarta.apache.org/taglibs/doc/utility-doc/intro.html"/>
  +      <item name="XSL Taglib"      href="http://jakarta.apache.org/taglibs/doc/xsl-doc/intro.html"/>
  +      <item name="XTags Taglib"    href="http://jakarta.apache.org/taglibs/doc/xtags-doc/intro.html"/>
  +    </menu>
  +    
  +    <menu name="Unsupported Tag Libraries">
  +      <item name="SQL Sample Taglib"      href="http://jakarta.apache.org/taglibs/doc/sql-doc/intro.html"/>
  +    </menu>
  +    
  +    <menu name="Custom Tag Library Extensions">
  +      <item name="UltraDev 4.0" href="http://jakarta.apache.org/taglibs/doc/ultradev4/intro.html"/>
  +    </menu>
  +
  +    <menu name="Documentation">
  +      <item name="Binary Dist" href="binarydist.html"/>
  +      <item name="Source Dist" href="sourcedist.html"/>
  +      <item name="Tutorial" href="tutorial.html"/>
  +      <item name="Guidelines" href="guidelines.html"/>
  +    </menu>
  +
  +    <menu name="Getting Involved">
  +      <item name="Overview" href="http://jakarta.apache.org/site/getinvolved.html"/>
  +      <item name="CVS Repositories" href="http://jakarta.apache.org/site/cvsindex.html"/>
  +      <item name="Mailing Lists" href="http://jakarta.apache.org/site/mail.html"/>
  +      <item name="Reference Library" href="http://jakarta.apache.org/site/library.html"/>
  +      <item name="Bug Database" href="http://jakarta.apache.org/site/bugs.html"/>
  +    </menu>
  +
  +</project>
  
  
  
  1.1                  jakarta-taglibs/src/doc/guidelines.xml
  
  Index: guidelines.xml
  ===================================================================
  <?xml version="1.0"?>
  <document url="./guidelines.xml">
  
    <properties>
      <author>Shawn Bayern</author>
      <title>Taglib Developer Guidelines</title>
    </properties>
  
    <body>
  
  
    <section name="Taglib Developer Guidelines" href="Guidelines">
      <p>This guide attempts to give Tag Library authors a summary
        of guidelines and issues to be careful of when developing custom JSP tags.
      </p>
  
    <section name="Guidelines for tag lifecycle management" href="Lifecycle">    
      <ol>
        <li>
          Properties are expected to remain consistent.  This means that:
          <ul>
            <li>
              user code should avoid calling a a setter method of a tag handler
              for properties that correspond to tag attributes.  That is, if
              a tag has a "value" attribute, user code should avoid calling
              setValue() for that tag's handler.
            </li>
            <li>
              the tag handler's code itself should not modify properties that are
              set by a setXXX() method
            </li>
            <li>
              tag handlers should not perform invocation-specific logic in a
              setXXX() method.  That is, the setting of a property should
              have no side effects.
            </li>
          </ul>
        </li>
  
        <li>
          Private, invocation-specific state must be managed manually.  
          Implications include that:
          <ul>
            <li>
              release() is not necessarily called between invocations, which
              means that tag logic should not count on private invocation-
              specific state being reset by release()
            </li>
            <li>
              doEndTag() is not necessarily called at the end of every invocation
              (in cases of abnormal termination -- e.g., an exception thrown inside
              a tag's body or by one of its methods)
            </li>
            <li>
              private invocation-specific state is thus best initialized in
              doStartTag()
            </li>
            <li>
              doFinally() *is* always called for tag handlers that implement
              TryCatchFinally, so this method should be used if any invocation-
              specific resources need to be released
            </li>
            <li>
              release() *is* always called at least once for a tag handler before
              it is garbage-collected, so this method can and should be used to
              release any long-term resources
            </li>
          </ul>
        </li>
  
        <li>
          Since tags may be re-used, user code should not refer to a tag handler
          beyond its natural scope.  This implies:
          <ul>
            <li>
              a tag handler must not expose itself as a scripting variable if
              that variable has AT_BEGIN or AT_END scope (although NESTED scope
              would not be problematic in this case).
            </li>
            <li>
              a tag handler should not set a reference to itself in the
              PageContext associated with the page for which it is invoked,
              unless expected use of such a reference would occur only during
              the invocation of the tag handler.
            </li>
          </ul>
        </li>
      </ol>
    </section>
  
  
    <section name="Examples" href="Examples">    
      <ol>
        <li>
          Suppose you have a tag that accepts some sort of expression that you
          need to resolve, e.g.:
  
          <pre>&lt;show value="$my-expression$"/&gt;</pre>
  
          <p>  
            "$my-expression$" should be stored by setValue() and evaluated (i.e.,
            resolved) in doStartTag().  For the behavior that's almost always
            desired, it should NOT be evaluated in setValue().  (Validation, such
            as syntax checking, is acceptable in the setter method.)
          </p>
          <p>
            Similarly, Iterators and Enumerations should not be extracted in a
            setXXX() method.  setXXX() methods are meant to be "idempotent";
            write them so that they can be called multiple times with no
            side effects (and, conversely, only once instead of multiple times
            if the argument passed is the same).
          </p>
        </li>
        <li>
          Private state that's kept for each invocation should typically be
          reset in doStartTag(), not in release().  If you have an iteration
          index controlling the behavior of a loop, doStartTag() is the
          appropriate method from which to initialize it.
        </li>
        <li>
          If a tag needs to open a new database connection (or file, or other
          external resource) for every invocation, the tag handler should
          implement TryCatchFinally and close the database connection (or
          other resource) in doFinally().  doEndTag() might not be called,
          and release() might not be called until long after you expect it to be.
        </li>
      </ol>
    </section>
  
    </section>
  
  
  
    </body>
  </document>
  
  
  

Mime
View raw message