1 /* 2 * Copyright (c) 1996, 2024, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.io; 27 28 import java.lang.reflect.Field; 29 import jdk.internal.reflect.CallerSensitive; 30 import jdk.internal.reflect.Reflection; 31 import sun.reflect.misc.ReflectUtil; 32 33 /** 34 * A description of a Serializable field from a Serializable class. An array 35 * of ObjectStreamFields is used to declare the Serializable fields of a class. 36 * 37 * @author Mike Warres 38 * @author Roger Riggs 39 * @see ObjectStreamClass 40 * @since 1.2 41 */ 42 public class ObjectStreamField 43 implements Comparable<Object> 44 { 45 46 /** field name */ 47 private final String name; 48 /** canonical JVM signature of field type, if given */ 49 private final String signature; 50 /** field type (Object.class if unknown non-primitive type) */ 51 private final Class<?> type; 52 /** lazily constructed signature for the type, if no explicit signature */ 53 private String typeSignature; 54 /** whether or not to (de)serialize field values as unshared */ 55 private final boolean unshared; 56 /** corresponding reflective field object, if any */ 57 private final Field field; 58 /** offset of field value in enclosing field group */ 59 private int offset; 60 /** index of the field in the class, retain the declaration order of serializable fields */ 61 private final int argIndex; 62 63 /** 64 * Create a Serializable field with the specified type. This field should 65 * be documented with a {@code serialField} tag. 66 * 67 * @param name the name of the serializable field 68 * @param type the {@code Class} object of the serializable field 69 */ 70 public ObjectStreamField(String name, Class<?> type) { 71 this(name, type, false); 72 } 73 74 /** 75 * Creates an ObjectStreamField representing a serializable field with the 76 * given name and type. If unshared is false, values of the represented 77 * field are serialized and deserialized in the default manner--if the 78 * field is non-primitive, object values are serialized and deserialized as 79 * if they had been written and read by calls to writeObject and 80 * readObject. If unshared is true, values of the represented field are 81 * serialized and deserialized as if they had been written and read by 82 * calls to writeUnshared and readUnshared. 83 * 84 * @param name field name 85 * @param type field type 86 * @param unshared if false, write/read field values in the same manner 87 * as writeObject/readObject; if true, write/read in the same 88 * manner as writeUnshared/readUnshared 89 * @since 1.4 90 */ 91 public ObjectStreamField(String name, Class<?> type, boolean unshared) { 92 this(name, type, unshared, -1); 93 } 94 95 /* package-private */ 96 ObjectStreamField(String name, Class<?> type, boolean unshared, int argIndex) { 97 if (name == null) { 98 throw new NullPointerException(); 99 } 100 this.name = name; 101 this.type = type; 102 this.unshared = unshared; 103 this.field = null; 104 this.signature = null; 105 this.argIndex = argIndex; 106 } 107 108 /** 109 * Creates an ObjectStreamField representing a field with the given name, 110 * signature and unshared setting. 111 */ 112 ObjectStreamField(String name, String signature, boolean unshared, int argIndex) { 113 if (name == null) { 114 throw new NullPointerException(); 115 } 116 this.name = name; 117 this.signature = signature.intern(); 118 this.unshared = unshared; 119 this.field = null; 120 this.argIndex = argIndex; 121 122 type = switch (signature.charAt(0)) { 123 case 'Z' -> Boolean.TYPE; 124 case 'B' -> Byte.TYPE; 125 case 'C' -> Character.TYPE; 126 case 'S' -> Short.TYPE; 127 case 'I' -> Integer.TYPE; 128 case 'J' -> Long.TYPE; 129 case 'F' -> Float.TYPE; 130 case 'D' -> Double.TYPE; 131 case 'L', '[' -> Object.class; 132 default -> throw new IllegalArgumentException("illegal signature"); 133 }; 134 } 135 136 /** 137 * Creates an ObjectStreamField representing the given field with the 138 * specified unshared setting. For compatibility with the behavior of 139 * earlier serialization implementations, a "showType" parameter is 140 * necessary to govern whether or not a getType() call on this 141 * ObjectStreamField (if non-primitive) will return Object.class (as 142 * opposed to a more specific reference type). 143 */ 144 ObjectStreamField(Field field, boolean unshared, boolean showType, int argIndex) { 145 this.field = field; 146 this.unshared = unshared; 147 name = field.getName(); 148 Class<?> ftype = field.getType(); 149 type = (showType || ftype.isPrimitive()) ? ftype : Object.class; 150 signature = ftype.descriptorString().intern(); 151 this.argIndex = argIndex; 152 } 153 154 /** 155 * Get the name of this field. 156 * 157 * @return a {@code String} representing the name of the serializable 158 * field 159 */ 160 public String getName() { 161 return name; 162 } 163 164 /** 165 * Get the type of the field. If the type is non-primitive and this 166 * {@code ObjectStreamField} was obtained from a deserialized {@link 167 * ObjectStreamClass} instance, then {@code Object.class} is returned. 168 * Otherwise, the {@code Class} object for the type of the field is 169 * returned. 170 * 171 * @return a {@code Class} object representing the type of the 172 * serializable field 173 */ 174 @SuppressWarnings("removal") 175 @CallerSensitive 176 public Class<?> getType() { 177 if (System.getSecurityManager() != null) { 178 Class<?> caller = Reflection.getCallerClass(); 179 if (ReflectUtil.needsPackageAccessCheck(caller.getClassLoader(), type.getClassLoader())) { 180 ReflectUtil.checkPackageAccess(type); 181 } 182 } 183 return type; 184 } 185 186 /** 187 * Returns character encoding of field type. The encoding is as follows: 188 * <blockquote><pre> 189 * B byte 190 * C char 191 * D double 192 * F float 193 * I int 194 * J long 195 * L class or interface 196 * S short 197 * Z boolean 198 * [ array 199 * </pre></blockquote> 200 * 201 * @return the typecode of the serializable field 202 */ 203 // REMIND: deprecate? 204 public char getTypeCode() { 205 return getSignature().charAt(0); 206 } 207 208 /** 209 * Return the JVM type signature. 210 * 211 * @return null if this field has a primitive type. 212 */ 213 // REMIND: deprecate? 214 public String getTypeString() { 215 return isPrimitive() ? null : getSignature(); 216 } 217 218 /** 219 * Offset of field within instance data. 220 * 221 * @return the offset of this field 222 * @see #setOffset 223 */ 224 // REMIND: deprecate? 225 public int getOffset() { 226 return offset; 227 } 228 229 /** 230 * Offset within instance data. 231 * 232 * @param offset the offset of the field 233 * @see #getOffset 234 */ 235 // REMIND: deprecate? 236 protected void setOffset(int offset) { 237 this.offset = offset; 238 } 239 240 /** 241 * {@return Index of the field in the sequence of Serializable fields} 242 */ 243 int getArgIndex() { 244 return argIndex; 245 } 246 247 /** 248 * Return true if this field has a primitive type. 249 * 250 * @return true if and only if this field corresponds to a primitive type 251 */ 252 // REMIND: deprecate? 253 public boolean isPrimitive() { 254 char tcode = getTypeCode(); 255 return ((tcode != 'L') && (tcode != '[')); 256 } 257 258 /** 259 * Returns boolean value indicating whether or not the serializable field 260 * represented by this ObjectStreamField instance is unshared. 261 * 262 * @return {@code true} if this field is unshared 263 * 264 * @since 1.4 265 */ 266 public boolean isUnshared() { 267 return unshared; 268 } 269 270 /** 271 * Compare this field with another {@code ObjectStreamField}. Return 272 * -1 if this is smaller, 0 if equal, 1 if greater. Types that are 273 * primitives are "smaller" than object types. If equal, the field names 274 * are compared. 275 */ 276 // REMIND: deprecate? 277 public int compareTo(Object obj) { 278 ObjectStreamField other = (ObjectStreamField) obj; 279 boolean isPrim = isPrimitive(); 280 if (isPrim != other.isPrimitive()) { 281 return isPrim ? -1 : 1; 282 } 283 return name.compareTo(other.name); 284 } 285 286 /** 287 * Return a string that describes this field. 288 */ 289 public String toString() { 290 return getSignature() + ' ' + name; 291 } 292 293 /** 294 * Returns field represented by this ObjectStreamField, or null if 295 * ObjectStreamField is not associated with an actual field. 296 */ 297 Field getField() { 298 return field; 299 } 300 301 /** 302 * Returns JVM type signature of field (similar to getTypeString, except 303 * that signature strings are returned for primitive fields as well). 304 */ 305 String getSignature() { 306 if (signature != null) { 307 return signature; 308 } 309 310 String sig = typeSignature; 311 // This lazy calculation is safe since signature can be null iff one 312 // of the public constructors are used, in which case type is always 313 // initialized to the exact type we want the signature to represent. 314 if (sig == null) { 315 typeSignature = sig = type.descriptorString().intern(); 316 } 317 return sig; 318 } 319 } --- EOF ---