Class DetailsException

  • All Implemented Interfaces:
    java.io.Serializable
    public class DetailsException
extends java.lang.IllegalArgumentException
    Exception that may be thrown when erroneous-input is provided to internal-class Details or ReflHTML. These classes throw exceptions, rather than printing errors to the messager, since they may be called, externally, by the end-users. Those classes are not strictly limited to internal-use.
    See Also:
    ReflHTML, Serialized Form


    • Field Summary

       
      Serializable ID
      Modifier and Type Field
      static long serialVersionUID
       
      Static String-Constant Warning Messages
      Modifier and Type Field
      protected static String PLEASE_USE
      protected static String PLEASE_USE_ANNOT

    • Constructor Summary

      Constructors 
      Constructor Description
      DetailsException()
      Constructs a DetailsException with no detail message.
      DetailsException​(String message)
      Constructs a DetailsException with the specified detail message.
      DetailsException​(String message, Throwable cause)
      Constructs a new exception with the specified detail message and cause.
      DetailsException​(Throwable cause)
      Constructs a new exception with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).

    • Method Summary

       
      'static' Exception Check Methods
      Modifier and Type Method
      static void check​(Vector<HTMLNode> details)
      static void checkAnnotation​(Vector<HTMLNode> details)

      • Methods inherited from class java.lang.Throwable

        addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • serialVersionUID

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static final long serialVersionUID
        This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.

        Note that Java's java.lang.Exception and java.lang.Error classes implement the Serializable interface, and a warning-free build expects this field be defined here.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         public static final long serialVersionUID = 1;

      • PLEASE_USE

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected static final java.lang.String PLEASE_USE
        This is a helpful message explaining how to ensure that a sub-section of a vectorized-HTML Documentation Web-Page is properly formatted according to the 'details' section of a Java-Doc page.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         protected static final String PLEASE_USE =
         "Please use the Details iterator(); Methods to retrieve a details section for a " +
         "Method, Field, Constructor or Enumerated-Constant.";

      • PLEASE_USE_ANNOT

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected static final java.lang.String PLEASE_USE_ANNOT
        This is the message used for explaining how to retrieve an iterator of the 'details' section for an Annotation Java-Doc page.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         protected static final String PLEASE_USE_ANNOT =
         "Please use the Details iterator(); Methods to retrieve a details section for " +
         "the Annotation Elements.";

    • Constructor Detail

      • DetailsException

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public DetailsException​(java.lang.String message)
        Constructs a DetailsException with the specified detail message.
        Parameters:
        message - the detail message.

      • DetailsException

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public DetailsException​(java.lang.String message,
                        java.lang.Throwable cause)
        Constructs a new exception with the specified detail message and cause.

        NOTE:

        The detail message associated with cause is not automatically incorporated into this exception's detail message.
        Parameters:
        message - The detail message (which is saved for later retrieval by the Throwable.getMessage() method).
        cause - the cause (which is saved for later retrieval by the Throwable.getCause() method). (A null value is permitted, and indicates that the cause is nonexistent or unknown.)

      • DetailsException

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public DetailsException​(java.lang.Throwable cause)
        Constructs a new exception with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).

        This constructor is useful for exceptions that are little more than wrappers for other throwables.
        Parameters:
        cause - The cause (which is saved for later retrieval by the Throwable.getCause() method). (A null value is permitted, and indicates that the cause is nonexistent or unknown.)

    • Method Detail

      • check

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static void check​(java.util.Vector<HTMLNode> details)
        This check method is used to ensure that a passed-parameter vectorized-HTML sub-page to one of the DetailsPartMethods, DetailsPartConstructors or DetailsPartFields is a properly formatted HTML Sub-Section. The purpose of the iterators within class Details is to retrieve the individual, detailed descriptions for the fields, methods and constructors from an HTML Page generated by the Java-Doc tool. This exception class will do some simple, basic parameter checking to ensure that the proper parameters are passed. The priority is to provide more useable and meaningful error information.
        Parameters:
        details - This is supposed to be the return value from a call to the HNLIInclusive iter.next() method. The iterator should be one returned from the class Details iterator' methods. If it was, then it should a guarantee that the section is properly formatted, because it would have been retrieved from a JavaDoc HTML page.
        Throws:
        DetailsException - This exception shall throw if any of the requirements of the section have not been met.
        See Also:
        StrCmpr, TagNode
        Code:
        Exact Method Body:
         TagNode first   = null;
 TagNode last    = null;

 // Ensure that the section is not null.
 if (details == null) throw new NullPointerException
     ("The vectorized-HTML section vector-reference was null.");

 // There should quite a number of elements in this vector, besides the beginning and
 // ending <UL>...</UL> elements.
 if (details.size() < 3) throw new DetailsException(
     "The vectorized-HTML section parameter has v.size()=" + details.size() +
     ".  This is not sufficient.  " + PLEASE_USE
 );

 // All Details Elements begin with <ul class='blockList'> or <ul class='blockListLast'>
 try
     { first = (TagNode) details.elementAt(0); }
 catch (ClassCastException e)
 { 
     throw new DetailsException(
         "This vectorized-HTML section does not begin with a TagNode element.  " +
         "It begins with [" + first.str + "]" + PLEASE_USE
     );
 }

 // All  Details Elements end with </ul>
 try
     { last = (TagNode) details.elementAt(details.size() - 1); }
 catch (ClassCastException e)
 {
     throw new DetailsException(
         "This vectorized-HTML section does not end with a TagNode element.  " + 
         "It ends with [" + last.str + "]" + PLEASE_USE
     );
 }

 // All  Details Elements begin with <ul class='blockList'> or <ul class='blockListLast'>
 if ((! first.tok.equals("ul")) || first.isClosing)
     throw new DetailsException(
         "The first node of the vectorized-HTML section is not an Opening <UL> Element.  " + 
         "It is a [" + first.str + "].  " + PLEASE_USE
     );

 // All  Details Elements end with </ul>
 if ((! last.tok.equals("ul")) || (! last.isClosing))
     throw new DetailsException(
         "The last node of the vectorized-HTML section is not a Closing </UL> Element.  " +
         "It is a [" + last.str + "].  " + PLEASE_USE
     );

 // All Details Elements begin with <ul class='blockList'> or <ul class='blockListLast'>
 if (! StrCmpr.containsOR_CI(first.AV("class"), "blockList", "blockListLast"))
     throw new DetailsException(
         "The first node of the vectorized-HTML section is not an Opening <UL> Element " +
         "with 'class' attribute containing string: 'blockList' or 'blockListLast.'  " +
         "Instead it is: [" + first.str + "]."
     );

      • checkAnnotation

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public static void checkAnnotation​(java.util.Vector<HTMLNode> details)
        This check method is used to ensure that a passed-parameter vectorized-HTML sub-page is correct.

        NOTE: The Annotation-Element Details are just ever so slightly different than they are for the other four types of details (Methods, Constructors, Fields, and Enumerated-Constants). The Annotation-Element Iterator returns HTML <SECTION> elements instead!
        Parameters:
        details - This is supposed to be the return value from a call to the HNLIInclusive iter.next() method. The iterator should be one returned from the class Details methods retreiving an Annotation-Element Iterator.
        Throws:
        DetailsException - This exception shall throw if any of the requirements of the section have not been met.
        See Also:
        StrCmpr, TagNode
        Code:
        Exact Method Body:
         TagNode first   = null;
 TagNode last    = null;

 // Ensure that the section is not null.
 if (details == null) throw new NullPointerException
     ("The vectorized-HTML section vector-reference was null.");

 // There should quite a number of elements in this vector, besides the beginning and
 // ending <UL>...</UL> elements.
 if (details.size() < 3) throw new DetailsException(
     "The vectorized-HTML section parameter has v.size()=" + details.size() +
     ".  This is not sufficient.  " + PLEASE_USE
 );

 // All Details Elements begin with <ul class='blockList'> or <ul class='blockListLast'>
 try
     { first = (TagNode) details.elementAt(0); }
 catch (ClassCastException e)
 { 
     throw new DetailsException(
         "This vectorized-HTML section does not begin with a TagNode element.  " +
         "It begins with [" + first.str + "]" + PLEASE_USE_ANNOT
     );
 }

 // All  Details Elements end with </ul>
 try
     { last = (TagNode) details.elementAt(details.size() - 1); }
 catch (ClassCastException e)
 {
     throw new DetailsException(
         "This vectorized-HTML section does not end with a TagNode element.  " + 
         "It ends with [" + last.str + "]" + PLEASE_USE_ANNOT
     );
 }

 // All  Details Elements begin with <ul class='blockList'> or <ul class='blockListLast'>
 if ((! first.tok.equals("section")) || first.isClosing)
     throw new DetailsException(
         "The first node of the vectorized-HTML section is not an Opening <SECTION> " +
         "Element.  It is a [" + first.str + "].  " + PLEASE_USE_ANNOT
     );

 // All  Details Elements end with </ul>
 if ((! last.tok.equals("section")) || (! last.isClosing))
     throw new DetailsException(
         "The last node of the vectorized-HTML section is not a Closing </SECTION> " +
         "Element.  It is a [" + last.str + "].  " + PLEASE_USE_ANNOT
     );

 // All Details Elements begin with <ul class='blockList'> or <ul class='blockListLast'>
 if (! StrCmpr.containsOR_CI(first.AV("role"), "region"))
     throw new DetailsException(
         "The first node of the vectorized-HTML section is not an Opening <SECTION> " +
         "element with 'role' attribute containing string: 'region.'  " +
         "Instead it is: [" + first.str + "]."
     );