/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright 2000-2009 Sun Microsystems, Inc. All rights reserved. 
 *
 * The contents of this file are subject to the terms of either the GNU
 * General Public License Version 2 only ("GPL") or the Common Development
 * and Distribution License ("CDDL") (collectively, the "License").  You may
 * not use this file except in compliance with the License.  You can obtain
 * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
 * or mq/legal/LICENSE.txt.  See the License for the specific language
 * governing permissions and limitations under the License.
 * 
 * When distributing the software, include this License Header Notice in each
 * file and include the License file at mq/legal/LICENSE.txt.  Sun designates
 * this particular file as subject to the "Classpath" exception as provided by
 * Sun in the GPL Version 2 section of the License file that accompanied this
 * code.  If applicable, add the following below the License Header, with the
 * fields enclosed by brackets [] replaced by your own identifying information:
 * "Portions Copyrighted [year] [name of copyright owner]"
 * 
 * Contributor(s):
 * 
 * If you wish your version of this file to be governed by only the CDDL or
 * only the GPL Version 2, indicate your decision by adding "[Contributor]
 * elects to include this software in this distribution under the [CDDL or GPL
 * Version 2] license."  If you don't indicate a single choice of license, a
 * recipient has the option to distribute your version of this file under
 * either the CDDL, the GPL Version 2 or  to extend the choice of license to
 * its licensees as provided above.  However, if you add GPL Version 2 code
 * and therefore, elected the GPL Version 2 license, then the option applies
 * only if the new code is made subject to such option by the copyright holder. 
 */

/*
 * @(#)JMQByteArrayOutputStream.java	1.3 06/27/07
 */ 

package com.sun.messaging.jmq.io;

import java.io.ByteArrayOutputStream;

/**
 * This class extends ByteArrayOutputStream to provide the ability
 * to more directly manage the backing buffer to reduce the number of
 * memory allocations and data copies. In particular it supports
 * a constructor that accepts a byte array to use as the backing buffer
 * and an accessor to get the buffer back without making a copy.
 *
 * WARNING! Providing these hooks breaks the safe encapsulation that 
 * ByteArrayOutputStream provides, so be careful. In particular
 * please see the warning on the getBuf() method.
 */

public class JMQByteArrayOutputStream extends ByteArrayOutputStream {

    /**
     * Creates a new byte array output stream with the specified buffer
     * as the initial backing buffer. Note: the provided buffer may
     * be replaced with another buffer if the implementation finds it
     * necessary to do so (for example to increase the buffer size).
     * You should consider this constructor to be an optimization hint
     * and always use getBuf() to retrieve the backing buffer.
     * 
     * @param    size    the buffer to use as the backing buffer.
     */
    public JMQByteArrayOutputStream(byte newBuf[]) {
	// If we don't invoke a constructor the no-arg constructor is
	// invoked which allocates a 32 byte buffer we don't want;
	super(0);
	buf = newBuf;
    }

    /**
     * Returns a reference to the backing buffer
     *
     * @return    a reference to the backing buffer. WARNING! This is a 
     *            reference to the buffer -- not a copy. Note that 
     *		  ByteArrayOutputStream will reallocate this buffer if it
     *		  needs more space -- so the buffer returned by getBuf()
     *		  may not match the buffer provided in the constructor!
     */
    public byte[] getBuf() {
	return buf;
    }

    /**
     * Returns the number of valid bytes in the buffer.
     *
     * @return    the number of valid bytes in the buffer.
     */
    public int getCount() {
	return count;
    }
}
