    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one
    003 * or more contributor license agreements.  See the NOTICE file
    004 * distributed with this work for additional information
    005 * regarding copyright ownership.  The ASF licenses this file
    006 * to you under the Apache License, Version 2.0 (the
    007 * "License"); you may not use this file except in compliance
    008 * with the License.  You may obtain a copy of the License at
    009 *
    010 *   https://www.apache.org/licenses/LICENSE-2.0
    011 *
    012 * Unless required by applicable law or agreed to in writing,
    013 * software distributed under the License is distributed on an
    014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    015 * KIND, either express or implied.  See the License for the
    016 * specific language governing permissions and limitations
    017 * under the License.
    018 */
    019package org.apache.bcel.generic;
    020
    021/**
    022 * Thrown by {@link InstructionList} when one or multiple disposed instructions are still being referenced by an {@link InstructionTargeter} object. I.e. the
    023 * {@link InstructionTargeter} has to be notified that (one of) the {@link InstructionHandle} it is referencing is being removed from the
    024 * {@link InstructionList} and thus not valid anymore.
    025 *
    026 * <p>
    027 * Making this an exception instead of a return value forces the user to handle these case explicitly in a try { ... } catch. The following code illustrates how
    028 * this may be done:
    029 * </p>
    030 *
    031 * <pre>
    032 *     ...
    033 *     try {
    034 *         il.delete(start_ih, end_ih);
    035 *     } catch (TargetLostException e) {
    036 *         for (InstructionHandle target : e.getTargets()) {
    037 *             for (InstructionTargeter targeter : target.getTargeters()) {
    038 *                 targeter.updateTarget(target, new_target);
    039 *             }
    040 *         }
    041 *     }
    042 * </pre>
    043 *
    044 * @see InstructionHandle
    045 * @see InstructionList
    046 * @see InstructionTargeter
    047 */
    048public final class TargetLostException extends Exception {
    049
    050    private static final long serialVersionUID = -6857272667645328384L;
    051    private final InstructionHandle[] targets;
    052
    053    TargetLostException(final InstructionHandle[] targets, final String message) {
    054        super(message);
    055        this.targets = targets;
    056    }
    057
    058    /**
    059     * Gets the list of instructions still being targeted.
    060     *
    061     * @return list of instructions still being targeted.
    062     */
    063    public InstructionHandle[] getTargets() {
    064        return targets;
    065    }
    066}