/*
    * Licensed to the Apache Software Foundation (ASF) under one or more
    * contributor license agreements.  See the NOTICE file distributed with
    * this work for additional information regarding copyright ownership.
    * The ASF licenses this file to You under the Apache License, Version 2.0
    * (the "License"); you may not use this file except in compliance with
    * the License.  You may obtain a copy of the License at
    *
    *      http://www.apache.org/licenses/LICENSE-2.0
   *
   *  Unless required by applicable law or agreed to in writing, software
   *  distributed under the License is distributed on an "AS IS" BASIS,
   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   *  See the License for the specific language governing permissions and
   *  limitations under the License.
   */
  package org.apache.bcel.classfile;
  
  import java.io.DataInput;
  import java.io.DataOutputStream;
  import java.io.IOException;
  
  import org.apache.bcel.Constants;
  import org.apache.bcel.util.Args;
  
  /**
   * This class represents a local variable within a method. It contains its scope, name, signature and index on the
   * method's frame. It is used both to represent an element of the LocalVariableTable as well as an element of the
   * LocalVariableTypeTable. The nomenclature used here may be a bit confusing; while the two items have the same layout
   * in a class file, a LocalVariableTable attribute contains a descriptor_index, not a signatureIndex. The
   * LocalVariableTypeTable attribute does have a signatureIndex.
   *
   * @see org.apache.bcel.classfile.Utility for more details on the difference.
   *
   * @see LocalVariableTable
   * @see LocalVariableTypeTable
   */
  public final class LocalVariable implements Cloneable, Node, Constants {
  
      static final LocalVariable[] EMPTY_ARRAY = {};
  
      /** Range in which the variable is valid. */
      private int startPc;
  
      private int length;
  
      /** Index in constant pool of variable name. */
      private int nameIndex;
  
      /**
       * Technically, a decscriptor_index for a local variable table entry and a signatureIndex for a local variable type table entry. Index of variable signature
       */
      private int signatureIndex;
  
      /*
       * Variable is index'th local variable on this method's frame.
       */
      private int index;
  
      private ConstantPool constantPool;
  
      /** Never changes; used to match up with LocalVariableTypeTable entries. */
      private final int origIndex;
  
      /**
       * Constructs object from file stream.
       *
       * @param file Input stream
       * @throws IOException if an I/O error occurs.
       */
      LocalVariable(final DataInput file, final ConstantPool constantPool) throws IOException {
          this(file.readUnsignedShort(), file.readUnsignedShort(), file.readUnsignedShort(), file.readUnsignedShort(), file.readUnsignedShort(), constantPool);
      }
  
      /**
       * @param startPc Range in which the variable
       * @param length ... is valid
       * @param nameIndex Index in constant pool of variable name
       * @param signatureIndex Index of variable's signature
       * @param index Variable is 'index'th local variable on the method's frame
       * @param constantPool Array of constants
       */
      public LocalVariable(final int startPc, final int length, final int nameIndex, final int signatureIndex, final int index, final ConstantPool constantPool) {
          this(startPc, length, nameIndex, signatureIndex, index, constantPool, index);
      }
  
      /**
       * @param startPc Range in which the variable
       * @param length ... is valid
       * @param nameIndex Index in constant pool of variable name
       * @param signatureIndex Index of variable's signature
       * @param index Variable is 'index'th local variable on the method's frame
       * @param constantPool Array of constants
       * @param origIndex Variable is 'index'th local variable on the method's frame prior to any changes
       */
      public LocalVariable(final int startPc, final int length, final int nameIndex, final int signatureIndex, final int index, final ConstantPool constantPool,
          final int origIndex) {
          this.startPc = Args.requireU2(startPc, "startPc");
          this.length = Args.requireU2(length, "length");
         this.nameIndex = Args.requireU2(nameIndex, "nameIndex");
         this.signatureIndex = Args.requireU2(signatureIndex, "signatureIndex");
         this.index = Args.requireU2(index, "index");
         this.origIndex = Args.requireU2(origIndex, "origIndex");
         this.constantPool = constantPool;
     }
 
     /**
      * Initializes from another LocalVariable. Note that both objects use the same references (shallow copy). Use copy() for
      * a physical copy.
      *
      * @param localVariable Another LocalVariable.
      */
     public LocalVariable(final LocalVariable localVariable) {
         this(localVariable.getStartPC(), localVariable.getLength(), localVariable.getNameIndex(), localVariable.getSignatureIndex(), localVariable.getIndex(),
             localVariable.getConstantPool());
     }
 
     /**
      * Called by objects that are traversing the nodes of the tree implicitly defined by the contents of a Java class.
      * I.e., the hierarchy of methods, fields, attributes, etc. spawns a tree of objects.
      *
      * @param v Visitor object
      */
     @Override
     public void accept(final Visitor v) {
         v.visitLocalVariable(this);
     }
 
     /**
      * @return deep copy of this object
      */
     public LocalVariable copy() {
         try {
             return (LocalVariable) clone();
         } catch (final CloneNotSupportedException e) {
             // TODO should this throw?
         }
         return null;
     }
 
     /**
      * Dumps local variable to file stream in binary format.
      *
      * @param dataOutputStream Output file stream
      * @throws IOException if an I/O error occurs.
      * @see java.io.FilterOutputStream#out
      */
     public void dump(final DataOutputStream dataOutputStream) throws IOException {
         dataOutputStream.writeShort(startPc);
         dataOutputStream.writeShort(length);
         dataOutputStream.writeShort(nameIndex);
         dataOutputStream.writeShort(signatureIndex);
         dataOutputStream.writeShort(index);
     }
 
     /**
      * @return Constant pool used by this object.
      */
     public ConstantPool getConstantPool() {
         return constantPool;
     }
 
     /**
      * @return index of register where variable is stored
      */
     public int getIndex() {
         return index;
     }
 
     /**
      * @return Variable is valid within getStartPC() .. getStartPC()+getLength()
      */
     public int getLength() {
         return length;
     }
 
     /**
      * @return Variable name.
      */
     public String getName() {
         return constantPool.getConstantUtf8(nameIndex).getBytes();
     }
 
     /**
      * @return Index in constant pool of variable name.
      */
     public int getNameIndex() {
         return nameIndex;
     }
 
     /**
      * @return index of register where variable was originally stored
      */
     public int getOrigIndex() {
         return origIndex;
     }
 
     /**
      * @return Signature.
      */
     public String getSignature() {
         return constantPool.getConstantUtf8(signatureIndex).getBytes();
     }
 
     /**
      * @return Index in constant pool of variable signature.
      */
     public int getSignatureIndex() {
         return signatureIndex;
     }
 
     /**
      * @return Start of range where the variable is valid
      */
     public int getStartPC() {
         return startPc;
     }
 
     /**
      * @param constantPool Constant pool to be used for this object.
      */
     public void setConstantPool(final ConstantPool constantPool) {
         this.constantPool = constantPool;
     }
 
     /**
      * @param index the index in the local variable table of this variable
      */
     public void setIndex(final int index) { // TODO unused
         this.index = index;
     }
 
     /**
      * @param length the length of this local variable
      */
     public void setLength(final int length) {
         this.length = length;
     }
 
     /**
      * @param nameIndex the index into the constant pool for the name of this variable
      */
     public void setNameIndex(final int nameIndex) { // TODO unused
         this.nameIndex = nameIndex;
     }
 
     /**
      * @param signatureIndex the index into the constant pool for the signature of this variable
      */
     public void setSignatureIndex(final int signatureIndex) { // TODO unused
         this.signatureIndex = signatureIndex;
     }
 
     /**
      * @param startPc Specify range where the local variable is valid.
      */
     public void setStartPC(final int startPc) { // TODO unused
         this.startPc = startPc;
     }
 
     /**
      * @return string representation.
      */
     @Override
     public String toString() {
         return toStringShared(false);
     }
 
     /*
      * Helper method shared with LocalVariableTypeTable
      */
     String toStringShared(final boolean typeTable) {
         final String name = getName();
         final String signature = Utility.signatureToString(getSignature(), false);
         final String label = "LocalVariable" + (typeTable ? "Types" : "");
         return label + "(startPc = " + startPc + ", length = " + length + ", index = " + index + ":" + signature + " " + name + ")";
     }
 }