/*
 * Javassist, a Java-bytecode translator toolkit.
 * Copyright (C) 1999- Shigeru Chiba. All Rights Reserved.
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License.  Alternatively, the contents of this file may be used under
 * the terms of the GNU Lesser General Public License Version 2.1 or later,
 * or the Apache License Version 2.0.
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 */

package javassist.bytecode.annotation;

import java.io.IOException;
import java.io.OutputStream;

import javassist.bytecode.ByteArray;
import javassist.bytecode.ConstPool;

A convenience class for constructing a
..Annotations_attribute.
See the source code of the AnnotationsAttribute.Copier class.
The following code snippet is an example of use of this class:
ConstPool pool = ...;
output = new ByteArrayOutputStream();
writer = new AnnotationsWriter(output, pool);
writer.numAnnotations(1);
writer.annotation("Author", 2);
writer.memberValuePair("name");      // element_value_pair
writer.constValueIndex("chiba");
writer.memberValuePair("address");   // element_value_pair
writer.constValueIndex("tokyo");
writer.close();
byte[] attribute_info = output.toByteArray();
AnnotationsAttribute anno
    = new AnnotationsAttribute(pool, AnnotationsAttribute.visibleTag,
                               attribute_info);

The code snippet above generates the annotation attribute
corresponding to this annotation:
 @Author(name = "chiba", address = "tokyo")

See Also:
AnnotationsAttribute
ParameterAnnotationsAttribute/**
 * A convenience class for constructing a
 * <code>..Annotations_attribute</code>.
 * See the source code of the <code>AnnotationsAttribute.Copier</code> class.
 *
 * <p>The following code snippet is an example of use of this class:
 *
 * <pre>
 * ConstPool pool = ...;
 * output = new ByteArrayOutputStream();
 * writer = new AnnotationsWriter(output, pool);
 *
 * writer.numAnnotations(1);
 * writer.annotation("Author", 2);
 * writer.memberValuePair("name");      // element_value_pair
 * writer.constValueIndex("chiba");
 * writer.memberValuePair("address");   // element_value_pair
 * writer.constValueIndex("tokyo");
 *
 * writer.close();
 * byte[] attribute_info = output.toByteArray();
 * AnnotationsAttribute anno
 *     = new AnnotationsAttribute(pool, AnnotationsAttribute.visibleTag,
 *                                attribute_info);
 * </pre>
 *
 * <p>The code snippet above generates the annotation attribute
 * corresponding to this annotation:
 *
 * <pre>
 * &nbsp;@Author(name = "chiba", address = "tokyo")
 * </pre>
 *
 * @see javassist.bytecode.AnnotationsAttribute
 * @see javassist.bytecode.ParameterAnnotationsAttribute
 */
public class AnnotationsWriter {
    protected OutputStream output;
    private ConstPool pool;

    
Constructs with the given output stream.
Params:
os –    the output stream.
cp –    the constant pool./**
     * Constructs with the given output stream.
     *
     * @param os    the output stream.
     * @param cp    the constant pool.
     */
    public AnnotationsWriter(OutputStream os, ConstPool cp) {
        output = os;
        pool = cp;
    }

    
Obtains the constant pool given to the constructor.
/**
     * Obtains the constant pool given to the constructor.
     */
    public ConstPool getConstPool() {
        return pool;
    }

    
Closes the output stream.
/**
     * Closes the output stream.
     *
     */
    public void close() throws IOException {
        output.close();
    }

    
Writes num_parameters in
Runtime(In)VisibleParameterAnnotations_attribute.
This method must be followed by num calls to
numAnnotations().
/**
     * Writes <code>num_parameters</code> in
     * <code>Runtime(In)VisibleParameterAnnotations_attribute</code>.
     * This method must be followed by <code>num</code> calls to
     * <code>numAnnotations()</code>.
     */
    public void numParameters(int num) throws IOException {
        output.write(num);
    }

    
Writes num_annotations in
Runtime(In)VisibleAnnotations_attribute.
This method must be followed by num calls to
annotation().
/**
     * Writes <code>num_annotations</code> in
     * <code>Runtime(In)VisibleAnnotations_attribute</code>.
     * This method must be followed by <code>num</code> calls to
     * <code>annotation()</code>.
     */
    public void numAnnotations(int num) throws IOException {
        write16bit(num);
    }

    
Writes annotation.
This method must be followed by numMemberValuePairs
calls to memberValuePair().
Params:
type –                  the annotation interface name.
numMemberValuePairs –   num_element_value_pairs
                             in annotation./**
     * Writes <code>annotation</code>.
     * This method must be followed by <code>numMemberValuePairs</code>
     * calls to <code>memberValuePair()</code>.
     *
     * @param type                  the annotation interface name.
     * @param numMemberValuePairs   <code>num_element_value_pairs</code>
     *                              in <code>annotation</code>.
     */
    public void annotation(String type, int numMemberValuePairs)
        throws IOException
    {
        annotation(pool.addUtf8Info(type), numMemberValuePairs);
    }

    
Writes annotation.
This method must be followed by numMemberValuePairs
calls to memberValuePair().
Params:
typeIndex –  type_index in annotation.
numMemberValuePairs –   num_element_value_pairs
                             in annotation./**
     * Writes <code>annotation</code>.
     * This method must be followed by <code>numMemberValuePairs</code>
     * calls to <code>memberValuePair()</code>.
     *
     * @param typeIndex  <code>type_index</code> in <code>annotation</code>.
     * @param numMemberValuePairs   <code>num_element_value_pairs</code>
     *                              in <code>annotation</code>.
     */
    public void annotation(int typeIndex, int numMemberValuePairs)
        throws IOException
    {
        write16bit(typeIndex);
        write16bit(numMemberValuePairs);
    }

    
Writes an element of a element_value_pairs array
in annotation.
This method must be followed by a
call to constValueIndex(), enumConstValue(),
etc.
Params:
memberName –        the element name./**
     * Writes an element of a <code>element_value_pairs</code> array
     * in <code>annotation</code>.
     * This method must be followed by a
     * call to <code>constValueIndex()</code>, <code>enumConstValue()</code>,
     * etc.
     *
     * @param memberName        the element name.
     */
    public void memberValuePair(String memberName) throws IOException {
        memberValuePair(pool.addUtf8Info(memberName));
    }

    
Writes an element of a element_value_pairs array
in annotation.
This method must be followed by a
call to constValueIndex(), enumConstValue(),
etc.
Params:
memberNameIndex –   element_name_index
                         in element_value_pairs array./**
     * Writes an element of a <code>element_value_pairs</code> array
     * in <code>annotation</code>.
     * This method must be followed by a
     * call to <code>constValueIndex()</code>, <code>enumConstValue()</code>,
     * etc.
     *
     * @param memberNameIndex   <code>element_name_index</code>
     *                          in <code>element_value_pairs</code> array.
     */
    public void memberValuePair(int memberNameIndex) throws IOException {
        write16bit(memberNameIndex);
    }

    
Writes tag and const_value_index 
in element_value.
Params:
value –     the constant value./**
     * Writes <code>tag</code> and <code>const_value_index</code> 
     * in <code>element_value</code>.
     *
     * @param value     the constant value.
     */
    public void constValueIndex(boolean value) throws IOException {
        constValueIndex('Z', pool.addIntegerInfo(value ? 1 : 0));
    }

    
Writes tag and const_value_index 
in element_value.
Params:
value –     the constant value./**
     * Writes <code>tag</code> and <code>const_value_index</code> 
     * in <code>element_value</code>.
     *
     * @param value     the constant value.
     */
    public void constValueIndex(byte value) throws IOException {
        constValueIndex('B', pool.addIntegerInfo(value));
    }

    
Writes tag and const_value_index 
in element_value.
Params:
value –     the constant value./**
     * Writes <code>tag</code> and <code>const_value_index</code> 
     * in <code>element_value</code>.
     *
     * @param value     the constant value.
     */
    public void constValueIndex(char value) throws IOException {
        constValueIndex('C', pool.addIntegerInfo(value));
    }

    
Writes tag and const_value_index 
in element_value.
Params:
value –     the constant value./**
     * Writes <code>tag</code> and <code>const_value_index</code> 
     * in <code>element_value</code>.
     *
     * @param value     the constant value.
     */
    public void constValueIndex(short value) throws IOException {
        constValueIndex('S', pool.addIntegerInfo(value));
    }

    
Writes tag and const_value_index 
in element_value.
Params:
value –     the constant value./**
     * Writes <code>tag</code> and <code>const_value_index</code> 
     * in <code>element_value</code>.
     *
     * @param value     the constant value.
     */
    public void constValueIndex(int value) throws IOException {
        constValueIndex('I', pool.addIntegerInfo(value));
    }

    
Writes tag and const_value_index 
in element_value.
Params:
value –     the constant value./**
     * Writes <code>tag</code> and <code>const_value_index</code> 
     * in <code>element_value</code>.
     *
     * @param value     the constant value.
     */
    public void constValueIndex(long value) throws IOException {
        constValueIndex('J', pool.addLongInfo(value));
    }

    
Writes tag and const_value_index 
in element_value.
Params:
value –     the constant value./**
     * Writes <code>tag</code> and <code>const_value_index</code> 
     * in <code>element_value</code>.
     *
     * @param value     the constant value.
     */
    public void constValueIndex(float value) throws IOException {
        constValueIndex('F', pool.addFloatInfo(value));
    }

    
Writes tag and const_value_index 
in element_value.
Params:
value –     the constant value./**
     * Writes <code>tag</code> and <code>const_value_index</code> 
     * in <code>element_value</code>.
     *
     * @param value     the constant value.
     */
    public void constValueIndex(double value) throws IOException {
        constValueIndex('D', pool.addDoubleInfo(value));
    }

    
Writes tag and const_value_index 
in element_value.
Params:
value –     the constant value./**
     * Writes <code>tag</code> and <code>const_value_index</code> 
     * in <code>element_value</code>.
     *
     * @param value     the constant value.
     */
    public void constValueIndex(String value) throws IOException {
        constValueIndex('s', pool.addUtf8Info(value));
    }

    
Writes tag and const_value_index 
in element_value.
Params:
tag –       tag in element_value.
index –     const_value_index
                             in element_value./**
     * Writes <code>tag</code> and <code>const_value_index</code> 
     * in <code>element_value</code>.
     *
     * @param tag       <code>tag</code> in <code>element_value</code>.
     * @param index     <code>const_value_index</code>
     *                              in <code>element_value</code>.
     */
    public void constValueIndex(int tag, int index)
        throws IOException
    {
        output.write(tag);
        write16bit(index);
    }

    
Writes tag and enum_const_value 
in element_value.
Params:
typeName –      the type name of the enum constant.
constName –     the simple name of the enum constant./**
     * Writes <code>tag</code> and <code>enum_const_value</code> 
     * in <code>element_value</code>.
     *
     * @param typeName      the type name of the enum constant.
     * @param constName     the simple name of the enum constant.
     */
    public void enumConstValue(String typeName, String constName)
        throws IOException
    {
        enumConstValue(pool.addUtf8Info(typeName),
                       pool.addUtf8Info(constName));
    }

    
Writes tag and enum_const_value 
in element_value.
Params:
typeNameIndex –       type_name_index
                             in element_value.
constNameIndex –     const_name_index
                             in element_value./**
     * Writes <code>tag</code> and <code>enum_const_value</code> 
     * in <code>element_value</code>.
     *
     * @param typeNameIndex       <code>type_name_index</code>
     *                              in <code>element_value</code>.
     * @param constNameIndex     <code>const_name_index</code>
     *                              in <code>element_value</code>.
     */
    public void enumConstValue(int typeNameIndex, int constNameIndex)
        throws IOException
    {
        output.write('e');
        write16bit(typeNameIndex);
        write16bit(constNameIndex);
    }

    
Writes tag and class_info_index 
in element_value.
Params:
name –      the class name./**
     * Writes <code>tag</code> and <code>class_info_index</code> 
     * in <code>element_value</code>.
     *
     * @param name      the class name.
     */
    public void classInfoIndex(String name) throws IOException {
        classInfoIndex(pool.addUtf8Info(name));
    }

    
Writes tag and class_info_index 
in element_value.
Params:
index –       class_info_index/**
     * Writes <code>tag</code> and <code>class_info_index</code> 
     * in <code>element_value</code>.
     *
     * @param index       <code>class_info_index</code>
     */
    public void classInfoIndex(int index) throws IOException {
        output.write('c');
        write16bit(index);
    }

    
Writes tag and annotation_value 
in element_value.
This method must be followed by a call to annotation().
/**
     * Writes <code>tag</code> and <code>annotation_value</code> 
     * in <code>element_value</code>.
     * This method must be followed by a call to <code>annotation()</code>.
     */
    public void annotationValue() throws IOException {
        output.write('@');
    }

    
Writes tag and array_value 
in element_value.
This method must be followed by numValues calls
to constValueIndex(), enumConstValue(),
etc.
Params:
numValues –     num_values
                     in array_value./**
     * Writes <code>tag</code> and <code>array_value</code> 
     * in <code>element_value</code>.
     * This method must be followed by <code>numValues</code> calls
     * to <code>constValueIndex()</code>, <code>enumConstValue()</code>,
     * etc.
     *
     * @param numValues     <code>num_values</code>
     *                      in <code>array_value</code>.
     */
    public void arrayValue(int numValues) throws IOException {
        output.write('[');
        write16bit(numValues);
    }

    protected void write16bit(int value) throws IOException {
        byte[] buf = new byte[2];
        ByteArray.write16bit(value, buf, 0);
        output.write(buf);
    }
}