View Javadoc

    1   /*
    2    * Copyright  2000-2004 The Apache Software Foundation
    3    *
    4    *  Licensed under the Apache License, Version 2.0 (the "License");
    5    *  you may not use this file except in compliance with the License.
    6    *  You may obtain a copy of the License at
    7    *
    8    *      http://www.apache.org/licenses/LICENSE-2.0
    9    *
    10   *  Unless required by applicable law or agreed to in writing, software
    11   *  distributed under the License is distributed on an "AS IS" BASIS,
    12   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   *  See the License for the specific language governing permissions and
    14   *  limitations under the License.
    15   *
    16   */
    17  package org.apache.bcel.verifier;
    18
    19  import java.util.ArrayList;
    20  import java.util.List;
    21
    22  /***
    23   * A PassVerifier actually verifies a class file; it is instantiated
    24   * by a Verifier.
    25   * The verification should conform with a certain pass as described
    26   * in The Java Virtual Machine Specification, 2nd edition.
    27   * This book describes four passes. Pass one means loading the
    28   * class and verifying a few static constraints. Pass two actually
    29   * verifies some other constraints that could enforce loading in
    30   * referenced class files. Pass three is the first pass that actually
    31   * checks constraints in the code array of a method in the class file;
    32   * it has two parts with the first verifying static constraints and
    33   * the second part verifying structural constraints (where a data flow
    34   * analysis is used for). The fourth pass, finally, performs checks
    35   * that can only be done at run-time.
    36   * JustIce does not have a run-time pass, but certain constraints that
    37   * are usually delayed until run-time for performance reasons are also
    38   * checked during the second part of pass three.
    39   * PassVerifier instances perform caching.
    40   * That means, if you really want a new verification run of a certain
    41   * pass you must use a new instance of a given PassVerifier.
    42   *
    43   * @version $Id: PassVerifier.java 386056 2006-03-15 11:31:56Z tcurdt $
    44   * @author Enver Haase
    45   * @see org.apache.bcel.verifier.Verifier
    46   * @see #verify()
    47   */
    48  public abstract class PassVerifier {
    49
    50      /*** The (warning) messages. */
    51      private List messages = new ArrayList(); //Type of elements: String
    52      /*** The VerificationResult cache. */
    53      private VerificationResult verificationResult = null;
    54
    55
    56      /***
    57       * This method runs a verification pass conforming to the
    58       * Java Virtual Machine Specification, 2nd edition, on a
    59       * class file.
    60       * PassVerifier instances perform caching;
    61       * i.e. if the verify() method once determined a VerificationResult,
    62       * then this result may be returned after every invocation of this
    63       * method instead of running the verification pass anew; likewise with
    64       * the result of getMessages().
    65       *
    66       * @see #getMessages()
    67       * @see #addMessage(String)
    68       */
    69      public VerificationResult verify() {
    70          if (verificationResult == null) {
    71              verificationResult = do_verify();
    72          }
    73          return verificationResult;
    74      }
    75
    76
    77      /*** Does the real verification work, uncached. */
    78      public abstract VerificationResult do_verify();
    79
    80
    81      /***
    82       * This method adds a (warning) message to the message pool of this
    83       * PassVerifier. This method is normally only internally used by
    84       * BCEL's class file verifier "JustIce" and should not be used from
    85       * the outside.
    86       *
    87       * @see #getMessages()
    88       */
    89      public void addMessage( String message ) {
    90          messages.add(message);
    91      }
    92
    93
    94      /***
    95       * Returns the (warning) messages that this PassVerifier accumulated
    96       * during its do_verify()ing work.
    97       *
    98       * @see #addMessage(String)
    99       * @see #do_verify()
    100      */
    101     public String[] getMessages() {
    102         verify(); // create messages if not already done (cached!)
    103         return (String[]) messages.toArray(new String[messages.size()]);
    104     }
    105 }