001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.io;
018
019 import java.io.IOException;
020 import java.io.OutputStream;
021
022 /**
023 * Dumps data in hexadecimal format.
024 * <p>
025 * Provides a single function to take an array of bytes and display it
026 * in hexadecimal form.
027 * <p>
028 * Origin of code: POI.
029 *
030 * @version $Id: HexDump.java 1302748 2012-03-20 01:35:32Z ggregory $
031 */
032 public class HexDump {
033
034 /**
035 * Instances should NOT be constructed in standard programming.
036 */
037 public HexDump() {
038 super();
039 }
040
041 /**
042 * Dump an array of bytes to an OutputStream. The output is formatted
043 * for human inspection, with a hexadecimal offset followed by the
044 * hexadecimal values of the next 16 bytes of data and the printable ASCII
045 * characters (if any) that those bytes represent printed per each line
046 * of output.
047 * <p>
048 * The offset argument specifies the start offset of the data array
049 * within a larger entity like a file or an incoming stream. For example,
050 * if the data array contains the third kibibyte of a file, then the
051 * offset argument should be set to 2048. The offset value printed
052 * at the beginning of each line indicates where in that larger entity
053 * the first byte on that line is located.
054 * <p>
055 * All bytes between the given index (inclusive) and the end of the
056 * data array are dumped.
057 *
058 * @param data the byte array to be dumped
059 * @param offset offset of the byte array within a larger entity
060 * @param stream the OutputStream to which the data is to be
061 * written
062 * @param index initial index into the byte array
063 *
064 * @throws IOException is thrown if anything goes wrong writing
065 * the data to stream
066 * @throws ArrayIndexOutOfBoundsException if the index is
067 * outside the data array's bounds
068 * @throws IllegalArgumentException if the output stream is null
069 */
070
071 public static void dump(byte[] data, long offset,
072 OutputStream stream, int index)
073 throws IOException, ArrayIndexOutOfBoundsException,
074 IllegalArgumentException {
075
076 if (index < 0 || index >= data.length) {
077 throw new ArrayIndexOutOfBoundsException(
078 "illegal index: " + index + " into array of length "
079 + data.length);
080 }
081 if (stream == null) {
082 throw new IllegalArgumentException("cannot write to nullstream");
083 }
084 long display_offset = offset + index;
085 StringBuilder buffer = new StringBuilder(74);
086
087 for (int j = index; j < data.length; j += 16) {
088 int chars_read = data.length - j;
089
090 if (chars_read > 16) {
091 chars_read = 16;
092 }
093 dump(buffer, display_offset).append(' ');
094 for (int k = 0; k < 16; k++) {
095 if (k < chars_read) {
096 dump(buffer, data[k + j]);
097 } else {
098 buffer.append(" ");
099 }
100 buffer.append(' ');
101 }
102 for (int k = 0; k < chars_read; k++) {
103 if (data[k + j] >= ' ' && data[k + j] < 127) {
104 buffer.append((char) data[k + j]);
105 } else {
106 buffer.append('.');
107 }
108 }
109 buffer.append(EOL);
110 stream.write(buffer.toString().getBytes());
111 stream.flush();
112 buffer.setLength(0);
113 display_offset += chars_read;
114 }
115 }
116
117 /**
118 * The line-separator (initializes to "line.separator" system property.
119 */
120 public static final String EOL =
121 System.getProperty("line.separator");
122 private static final char[] _hexcodes =
123 {
124 '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
125 'A', 'B', 'C', 'D', 'E', 'F'
126 };
127 private static final int[] _shifts =
128 {
129 28, 24, 20, 16, 12, 8, 4, 0
130 };
131
132 /**
133 * Dump a long value into a StringBuilder.
134 *
135 * @param _lbuffer the StringBuilder to dump the value in
136 * @param value the long value to be dumped
137 * @return StringBuilder containing the dumped value.
138 */
139 private static StringBuilder dump(StringBuilder _lbuffer, long value) {
140 for (int j = 0; j < 8; j++) {
141 _lbuffer
142 .append(_hexcodes[(int) (value >> _shifts[j]) & 15]);
143 }
144 return _lbuffer;
145 }
146
147 /**
148 * Dump a byte value into a StringBuilder.
149 *
150 * @param _cbuffer the StringBuilder to dump the value in
151 * @param value the byte value to be dumped
152 * @return StringBuilder containing the dumped value.
153 */
154 private static StringBuilder dump(StringBuilder _cbuffer, byte value) {
155 for (int j = 0; j < 2; j++) {
156 _cbuffer.append(_hexcodes[value >> _shifts[j + 6] & 15]);
157 }
158 return _cbuffer;
159 }
160
161 }