1 /*
   2  * Copyright (c) 1999, 2013, 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 javax.naming;
  27 
  28 /**
  29   * This class represents the binary form of the address of
  30   * a communications end-point.
  31   *<p>
  32   * A BinaryRefAddr consists of a type that describes the communication mechanism
  33   * and an opaque buffer containing the address description
  34   * specific to that communication mechanism. The format and interpretation of
  35   * the address type and the contents of the opaque buffer are based on
  36   * the agreement of three parties: the client that uses the address,
  37   * the object/server that can be reached using the address,
  38   * and the administrator or program that creates the address.
  39   *<p>
  40   * An example of a binary reference address is an BER X.500 presentation address.
  41   * Another example of a binary reference address is a serialized form of
  42   * a service's object handle.
  43   *<p>
  44   * A binary reference address is immutable in the sense that its fields
  45   * once created, cannot be replaced. However, it is possible to access
  46   * the byte array used to hold the opaque buffer. Programs are strongly
  47   * recommended against changing this byte array. Changes to this
  48   * byte array need to be explicitly synchronized.
  49   *
  50   * @author Rosanna Lee
  51   * @author Scott Seligman
  52   *
  53   * @see RefAddr
  54   * @see StringRefAddr
  55   * @since 1.3
  56   */
  57 
  58   /*
  59   * The serialized form of a BinaryRefAddr object consists of its type
  60   * name String and a byte array containing its "contents".
  61   */
  62 
  63 public class BinaryRefAddr extends RefAddr {
  64     /**
  65      * Contains the bytes of the address.
  66      * This field is initialized by the constructor and returned
  67      * using getAddressBytes() and getAddressContents().
  68      * @serial
  69      */
  70     private byte[] buf = null;
  71 
  72     /**
  73       * Constructs a new instance of BinaryRefAddr using its address type and a byte
  74       * array for contents.
  75       *
  76       * @param addrType A non-null string describing the type of the address.
  77       * @param src      The non-null contents of the address as a byte array.
  78       *                 The contents of src is copied into the new BinaryRefAddr.
  79       */
  80     public BinaryRefAddr(String addrType, byte[] src) {
  81         this(addrType, src, 0, src.length);
  82     }
  83 
  84     /**
  85       * Constructs a new instance of BinaryRefAddr using its address type and
  86       * a region of a byte array for contents.
  87       *
  88       * @param addrType A non-null string describing the type of the address.
  89       * @param src      The non-null contents of the address as a byte array.
  90       *                 The contents of src is copied into the new BinaryRefAddr.
  91       * @param offset   The starting index in src to get the bytes.
  92       *                 {@code 0 <= offset <= src.length}.
  93       * @param count    The number of bytes to extract from src.
  94       *                 {@code 0 <= count <= src.length-offset}.
  95       */
  96     public BinaryRefAddr(String addrType, byte[] src, int offset, int count) {
  97         super(addrType);
  98         buf = new byte[count];
  99         System.arraycopy(src, offset, buf, 0, count);
 100     }
 101 
 102     /**
 103       * Retrieves the contents of this address as an Object.
 104       * The result is a byte array.
 105       * Changes to this array will affect this BinaryRefAddr's contents.
 106       * Programs are recommended against changing this array's contents
 107       * and to lock the buffer if they need to change it.
 108       *
 109       * @return The non-null buffer containing this address's contents.
 110       */
 111     public Object getContent() {
 112         return buf;
 113     }
 114 
 115 
 116     /**
 117       * Determines whether obj is equal to this address.  It is equal if
 118       * it contains the same address type and their contents are byte-wise
 119       * equivalent.
 120       * @param obj      The possibly null object to check.
 121       * @return true if the object is equal; false otherwise.
 122       */
 123     public boolean equals(Object obj) {
 124         if ((obj != null) && (obj instanceof BinaryRefAddr)) {
 125             BinaryRefAddr target = (BinaryRefAddr)obj;
 126             if (addrType.compareTo(target.addrType) == 0) {
 127                 if (buf == null && target.buf == null)
 128                     return true;
 129                 if (buf == null || target.buf == null ||
 130                     buf.length != target.buf.length)
 131                     return false;
 132                 for (int i = 0; i < buf.length; i++)
 133                     if (buf[i] != target.buf[i])
 134                         return false;
 135                 return true;
 136             }
 137         }
 138         return false;
 139     }
 140 
 141     /**
 142       * Computes the hash code of this address using its address type and contents.
 143       * Two BinaryRefAddrs have the same hash code if they have
 144       * the same address type and the same contents.
 145       * It is also possible for different BinaryRefAddrs to have
 146       * the same hash code.
 147       *
 148       * @return The hash code of this address as an int.
 149       */
 150     public int hashCode() {
 151         int hash = addrType.hashCode();
 152         for (int i = 0; i < buf.length; i++) {
 153             hash += buf[i];     // %%% improve later
 154         }
 155         return hash;
 156     }
 157 
 158     /**
 159       * Generates the string representation of this address.
 160       * The string consists of the address's type and contents with labels.
 161       * The first 32 bytes of contents are displayed (in hexadecimal).
 162       * If there are more than 32 bytes, "..." is used to indicate more.
 163       * This string is meant to used for debugging purposes and not
 164       * meant to be interpreted programmatically.
 165       * @return The non-null string representation of this address.
 166       */
 167     public String toString(){
 168         StringBuilder str = new StringBuilder();
 169         str.append("Address Type: ").append(addrType).append('\n');
 170         str.append("AddressContents: ");
 171         for (int i = 0; i<buf.length && i < 32; i++) {
 172             str.append(Integer.toHexString(buf[i])).append(' ');
 173         }
 174         if (buf.length >= 32)
 175             str.append(" ...\n");
 176         return (str.toString());
 177     }
 178 
 179     /**
 180      * Use serialVersionUID from JNDI 1.1.1 for interoperability
 181      */
 182     private static final long serialVersionUID = -3415254970957330361L;
 183 }