1 /* 2 * ModeShape (http://www.modeshape.org) 3 * See the COPYRIGHT.txt file distributed with this work for information 4 * regarding copyright ownership. Some portions may be licensed 5 * to Red Hat, Inc. under one or more contributor license agreements. 6 * See the AUTHORS.txt file in the distribution for a full listing of 7 * individual contributors. 8 * 9 * ModeShape is free software. Unless otherwise indicated, all code in ModeShape 10 * is licensed to you under the terms of the GNU Lesser General Public License as 11 * published by the Free Software Foundation; either version 2.1 of 12 * the License, or (at your option) any later version. 13 * 14 * ModeShape is distributed in the hope that it will be useful, 15 * but WITHOUT ANY WARRANTY; without even the implied warranty of 16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 17 * Lesser General Public License for more details. 18 * 19 * You should have received a copy of the GNU Lesser General Public 20 * License along with this software; if not, write to the Free 21 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 22 * 02110-1301 USA, or see the FSF site: http://www.fsf.org. 23 */ 24 package org.modeshape.jcr.api; 25 26 import java.io.IOException; 27 import java.io.InputStream; 28 import javax.jcr.RepositoryException; 29 30 /** 31 * Replicates JCR 2.0's javax.jcr.Binary interface. 32 */ 33 public interface Binary { 34 35 /** 36 * Returns an InputStream representation of this value. Each call to getStream() returns a new stream. The API consumer is 37 * responsible for calling close() on the returned stream. If dispose() has been called on this Binary object, then this 38 * method will throw the runtime exception IllegalStateException. 39 * 40 * @return A stream representation of this value. 41 * @throws RepositoryException if an error occurs. 42 */ 43 public InputStream getStream() throws RepositoryException; 44 45 /** 46 * Reads successive bytes from the specified position in this Binary into the passed byte array until either the byte array is 47 * full or the end of the Binary is encountered. If dispose() has been called on this Binary object, then this method will 48 * throw the runtime exception IllegalStateException. 49 * 50 * @param b - the buffer into which the data is read. 51 * @param position - the position in this Binary from which to start reading bytes. 52 * @return the number of bytes read into the buffer, or -1 if there is no more data because the end of the Binary has been 53 * reached. 54 * @throws IOException if an I/O error occurs. 55 * @throws NullPointerException if b is null. 56 * @throws IllegalArgumentException if offset is negative. 57 * @throws RepositoryException if another error occurs. 58 */ 59 public int read( byte[] b, 60 long position ) throws IOException, RepositoryException; 61 62 /** 63 * Returns the size of this Binary value in bytes. If dispose() has been called on this Binary object, then this method will 64 * throw the runtime exception IllegalStateException. 65 * 66 * @return the size of this value in bytes. 67 * @throws RepositoryException if an error occurs. 68 */ 69 public long getSize() throws RepositoryException; 70 71 /** 72 * Releases all resources associated with this Binary object and informs the repository that these resources may now be 73 * reclaimed. An application should call this method when it is finished with the Binary object. 74 */ 75 public void dispose(); 76 77 }