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 }