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