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 */ 017package org.apache.wicket.util.crypt; 018 019import java.io.UnsupportedEncodingException; 020 021/** 022 * Converts String to and from bytes using the encodings required by the Java specification. These 023 * encodings are specified in <a 024 * href="http://java.sun.com/j2se/1.4.2/docs/api/java/nio/charset/Charset.html">Standard 025 * charsets</a> 026 * 027 * @see CharEncoding 028 * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/nio/charset/Charset.html">Standard 029 * charsets</a> 030 * @author <a href="mailto:ggregory@seagullsw.com">Gary Gregory</a> 031 * @version $Id$ 032 * @since 1.4 033 */ 034public class StringUtils 035{ 036 /** 037 * Encodes the given string into a sequence of bytes using the ISO-8859-1 charset, storing the 038 * result into a new byte array. 039 * 040 * @param string 041 * the String to encode 042 * @return encoded bytes 043 * @throws IllegalStateException 044 * Thrown when the charset is missing, which should be never according the the Java 045 * specification. 046 * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/nio/charset/Charset.html">Standard 047 * charsets</a> 048 * @see #getBytesUnchecked(String, String) 049 */ 050 public static byte[] getBytesIso8859_1(final String string) 051 { 052 return StringUtils.getBytesUnchecked(string, CharEncoding.ISO_8859_1); 053 } 054 055 /** 056 * Encodes the given string into a sequence of bytes using the US-ASCII charset, storing the 057 * result into a new byte array. 058 * 059 * @param string 060 * the String to encode 061 * @return encoded bytes 062 * @throws IllegalStateException 063 * Thrown when the charset is missing, which should be never according the the Java 064 * specification. 065 * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/nio/charset/Charset.html">Standard 066 * charsets</a> 067 * @see #getBytesUnchecked(String, String) 068 */ 069 public static byte[] getBytesUsAscii(final String string) 070 { 071 return StringUtils.getBytesUnchecked(string, CharEncoding.US_ASCII); 072 } 073 074 /** 075 * Encodes the given string into a sequence of bytes using the UTF-16 charset, storing the 076 * result into a new byte array. 077 * 078 * @param string 079 * the String to encode 080 * @return encoded bytes 081 * @throws IllegalStateException 082 * Thrown when the charset is missing, which should be never according the the Java 083 * specification. 084 * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/nio/charset/Charset.html">Standard 085 * charsets</a> 086 * @see #getBytesUnchecked(String, String) 087 */ 088 public static byte[] getBytesUtf16(final String string) 089 { 090 return StringUtils.getBytesUnchecked(string, CharEncoding.UTF_16); 091 } 092 093 /** 094 * Encodes the given string into a sequence of bytes using the UTF-16BE charset, storing the 095 * result into a new byte array. 096 * 097 * @param string 098 * the String to encode 099 * @return encoded bytes 100 * @throws IllegalStateException 101 * Thrown when the charset is missing, which should be never according the the Java 102 * specification. 103 * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/nio/charset/Charset.html">Standard 104 * charsets</a> 105 * @see #getBytesUnchecked(String, String) 106 */ 107 public static byte[] getBytesUtf16Be(final String string) 108 { 109 return StringUtils.getBytesUnchecked(string, CharEncoding.UTF_16BE); 110 } 111 112 /** 113 * Encodes the given string into a sequence of bytes using the UTF-16LE charset, storing the 114 * result into a new byte array. 115 * 116 * @param string 117 * the String to encode 118 * @return encoded bytes 119 * @throws IllegalStateException 120 * Thrown when the charset is missing, which should be never according the the Java 121 * specification. 122 * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/nio/charset/Charset.html">Standard 123 * charsets</a> 124 * @see #getBytesUnchecked(String, String) 125 */ 126 public static byte[] getBytesUtf16Le(final String string) 127 { 128 return StringUtils.getBytesUnchecked(string, CharEncoding.UTF_16LE); 129 } 130 131 /** 132 * Encodes the given string into a sequence of bytes using the UTF-8 charset, storing the result 133 * into a new byte array. 134 * 135 * @param string 136 * the String to encode 137 * @return encoded bytes 138 * @throws IllegalStateException 139 * Thrown when the charset is missing, which should be never according the the Java 140 * specification. 141 * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/nio/charset/Charset.html">Standard 142 * charsets</a> 143 * @see #getBytesUnchecked(String, String) 144 */ 145 public static byte[] getBytesUtf8(final String string) 146 { 147 return StringUtils.getBytesUnchecked(string, CharEncoding.UTF_8); 148 } 149 150 /** 151 * Encodes the given string into a sequence of bytes using the named charset, storing the result 152 * into a new byte array. 153 * <p> 154 * This method catches {@link UnsupportedEncodingException} and rethrows it as 155 * {@link IllegalStateException}, which should never happen for a required charset name. Use 156 * this method when the encoding is required to be in the JRE. 157 * </p> 158 * 159 * @param string 160 * the String to encode 161 * @param charsetName 162 * The name of a required {@link java.nio.charset.Charset} 163 * @return encoded bytes 164 * @throws IllegalStateException 165 * Thrown when a {@link UnsupportedEncodingException} is caught, which should never 166 * happen for a required charset name. 167 * @see CharEncoding 168 * @see String#getBytes(String) 169 */ 170 public static byte[] getBytesUnchecked(final String string, final String charsetName) 171 { 172 if (string == null) 173 { 174 return null; 175 } 176 try 177 { 178 return string.getBytes(charsetName); 179 } 180 catch (UnsupportedEncodingException e) 181 { 182 throw StringUtils.newIllegalStateException(charsetName, e); 183 } 184 } 185 186 private static IllegalStateException newIllegalStateException(final String charsetName, 187 final UnsupportedEncodingException e) 188 { 189 return new IllegalStateException(charsetName + ": " + e); 190 } 191 192 /** 193 * Constructs a new <code>String</code> by decoding the specified array of bytes using the given 194 * charset. 195 * <p> 196 * This method catches {@link UnsupportedEncodingException} and re-throws it as 197 * {@link IllegalStateException}, which should never happen for a required charset name. Use 198 * this method when the encoding is required to be in the JRE. 199 * </p> 200 * 201 * @param bytes 202 * The bytes to be decoded into characters 203 * @param charsetName 204 * The name of a required {@link java.nio.charset.Charset} 205 * @return A new <code>String</code> decoded from the specified array of bytes using the given 206 * charset. 207 * @throws IllegalStateException 208 * Thrown when a {@link UnsupportedEncodingException} is caught, which should never 209 * happen for a required charset name. 210 * @see CharEncoding 211 * @see String#String(byte[], String) 212 */ 213 public static String newString(final byte[] bytes, final String charsetName) 214 { 215 if (bytes == null) 216 { 217 return null; 218 } 219 try 220 { 221 return new String(bytes, charsetName); 222 } 223 catch (UnsupportedEncodingException e) 224 { 225 throw StringUtils.newIllegalStateException(charsetName, e); 226 } 227 } 228 229 /** 230 * Constructs a new <code>String</code> by decoding the specified array of bytes using the 231 * ISO-8859-1 charset. 232 * 233 * @param bytes 234 * The bytes to be decoded into characters 235 * @return A new <code>String</code> decoded from the specified array of bytes using the given 236 * charset. 237 * @throws IllegalStateException 238 * Thrown when a {@link UnsupportedEncodingException} is caught, which should never 239 * happen since the charset is required. 240 */ 241 public static String newStringIso8859_1(final byte[] bytes) 242 { 243 return StringUtils.newString(bytes, CharEncoding.ISO_8859_1); 244 } 245 246 /** 247 * Constructs a new <code>String</code> by decoding the specified array of bytes using the 248 * US-ASCII charset. 249 * 250 * @param bytes 251 * The bytes to be decoded into characters 252 * @return A new <code>String</code> decoded from the specified array of bytes using the given 253 * charset. 254 * @throws IllegalStateException 255 * Thrown when a {@link UnsupportedEncodingException} is caught, which should never 256 * happen since the charset is required. 257 */ 258 public static String newStringUsAscii(final byte[] bytes) 259 { 260 return StringUtils.newString(bytes, CharEncoding.US_ASCII); 261 } 262 263 /** 264 * Constructs a new <code>String</code> by decoding the specified array of bytes using the 265 * UTF-16 charset. 266 * 267 * @param bytes 268 * The bytes to be decoded into characters 269 * @return A new <code>String</code> decoded from the specified array of bytes using the given 270 * charset. 271 * @throws IllegalStateException 272 * Thrown when a {@link UnsupportedEncodingException} is caught, which should never 273 * happen since the charset is required. 274 */ 275 public static String newStringUtf16(final byte[] bytes) 276 { 277 return StringUtils.newString(bytes, CharEncoding.UTF_16); 278 } 279 280 /** 281 * Constructs a new <code>String</code> by decoding the specified array of bytes using the 282 * UTF-16BE charset. 283 * 284 * @param bytes 285 * The bytes to be decoded into characters 286 * @return A new <code>String</code> decoded from the specified array of bytes using the given 287 * charset. 288 * @throws IllegalStateException 289 * Thrown when a {@link UnsupportedEncodingException} is caught, which should never 290 * happen since the charset is required. 291 */ 292 public static String newStringUtf16Be(final byte[] bytes) 293 { 294 return StringUtils.newString(bytes, CharEncoding.UTF_16BE); 295 } 296 297 /** 298 * Constructs a new <code>String</code> by decoding the specified array of bytes using the 299 * UTF-16LE charset. 300 * 301 * @param bytes 302 * The bytes to be decoded into characters 303 * @return A new <code>String</code> decoded from the specified array of bytes using the given 304 * charset. 305 * @throws IllegalStateException 306 * Thrown when a {@link UnsupportedEncodingException} is caught, which should never 307 * happen since the charset is required. 308 */ 309 public static String newStringUtf16Le(final byte[] bytes) 310 { 311 return StringUtils.newString(bytes, CharEncoding.UTF_16LE); 312 } 313 314 /** 315 * Constructs a new <code>String</code> by decoding the specified array of bytes using the UTF-8 316 * charset. 317 * 318 * @param bytes 319 * The bytes to be decoded into characters 320 * @return A new <code>String</code> decoded from the specified array of bytes using the given 321 * charset. 322 * @throws IllegalStateException 323 * Thrown when a {@link UnsupportedEncodingException} is caught, which should never 324 * happen since the charset is required. 325 */ 326 public static String newStringUtf8(final byte[] bytes) 327 { 328 return StringUtils.newString(bytes, CharEncoding.UTF_8); 329 } 330}