AID (Java Card API, Connected Edition)
Date: 2009-12-11

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javacard.framework
Class AID

    java.lang.Object
      javacard.framework.AID

    @TransactionType(value=NOT_SUPPORTED)
    public class AID

extends Object

This class encapsulates the Application Identifier (AID) associated with an applet. An AID is defined in ISO 7816-5 to be a sequence of bytes between 5 and 16 bytes in length.

The Java Card runtime environment creates instances of `AID` class to identify and manage every applet on the card. Applets need not create instances of this class. An applet may request and use the Java Card runtime environment-owned instances to identify itself and other applet instances.

Java Card runtime environment-owned instances of `AID` are permanent Java Card runtime environment Entry Point Objects and can be accessed from any applet context. References to these permanent objects can be stored and re-used.

An applet instance can obtain a reference to Java Card runtime environment-owned instances of its own `AID` object by using the `JCSystem.getAID()` method and another applet's `AID` object via the `JCSystem.lookupAID()` method.

An applet uses `AID` instances to request to share another applet's object or to control access to its own shared object from another applet. See Runtime Environment Specification, Java Card Platform, Connected Edition, chapter 6 for details.

See Also:
  `JCSystem`, `SystemException`

Constructor Summary
`AID(byte[] bArray, short offset, byte length)` The Java Card runtime environment uses this constructor to create a new `AID` instance encapsulating the specified AID bytes.

Method Summary
`boolean` | `equals(byte[] bArray, short offset, byte length)` Checks if the specified AID bytes in `bArray` are the same as those encapsulated in `this` `AID` object.
`boolean` | `equals(Object anObject)` Compares the AID bytes in `this` `AID` instance to the AID bytes in the specified object.
`byte` | `getBytes(byte[] dest, short offset)` Called to get all the AID bytes encapsulated within `AID` object.
`byte` | `getPartialBytes(short aidOffset, byte[] dest, short oOffset, byte oLength)` Called to get part of the AID bytes encapsulated within the `AID` object starting at the specified offset for the specified length.
`int` | `hashCode()` Returns a hash code value for the object.
`boolean` | `partialEquals(byte[] bArray, short offset, byte length)` Checks if the specified partial AID byte sequence matches the first `length` bytes of the encapsulated AID bytes within `this` `AID` object.
`boolean` | `RIDEquals(AID otherAID)` Checks if the RID (National Registered Application provider identifier) portion of the encapsulated AID bytes within the `otherAID` object matches that of `this` `AID` object.

Methods inherited from class java.lang.Object
`getClass, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### AID

    public AID(byte[] bArray,
               short offset,
               byte length)
        throws SystemException,
               NullPointerException,
               ArrayIndexOutOfBoundsException,
               SecurityException

  The Java Card runtime environment uses this constructor to create a new `AID` instance encapsulating the specified AID bytes.

  Parameters:
    `bArray` - the byte array containing the AID bytes
    `offset` - the start of AID bytes in bArray
    `length` - the length of the AID bytes in bArray
  Throws:
    `SecurityException` - if the `bArray` array is not accessible in the caller's context
    `SystemException` - with the following reason code:
    - `SystemException.ILLEGAL_VALUE` if the `length` parameter is less than `5` or greater than `16`
    `NullPointerException` - if the `bArray` parameter is `null`
    `ArrayIndexOutOfBoundsException` - if the `offset` parameter or `length` parameter is negative or if `offset+length` is greater than the length of the `bArray` parameter

Method Detail

### getBytes

    public final byte getBytes(byte[] dest,
                               short offset)
                        throws NullPointerException,
                               ArrayIndexOutOfBoundsException,
                               SecurityException

  Called to get all the AID bytes encapsulated within `AID` object.

  Parameters:
    `dest` - byte array to copy the AID bytes
    `offset` - within dest where the AID bytes begin
  Returns:
    the length of the AID bytes
  Throws:
    `SecurityException` - if the `dest` array is not accessible in the caller's context
    `NullPointerException` - if the `dest` parameter is `null`
    `ArrayIndexOutOfBoundsException` - if the `offset` parameter is negative or `offset+`length of AID bytes is greater than the length of the `dest` array

### equals

    public final boolean equals(Object anObject)
                         throws SecurityException

  Compares the AID bytes in `this` `AID` instance to the AID bytes in the specified object. The result is `true` if and only if the argument is not `null` and is an `AID` object that encapsulates the same AID bytes as `this` object.

  This method does not throw `NullPointerException`.

  Overrides:
    `equals` in class `Object`
  Parameters:
    `anObject` - the object to compare `this` `AID` against
  Returns:
    `true` if the AID byte values are equal, `false` otherwise
  Throws:
    `SecurityException` - if `anObject` object is not accessible in the caller's context
  See Also:
    `Boolean.hashCode()`, `Hashtable`

### hashCode

    public int hashCode()

  Description copied from class: `Object`
  Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by `java.util.Hashtable`.

  The general contract of `hashCode` is:

  - Whenever it is invoked on the same object more than once during an execution of a Java application, the `hashCode` method must consistently return the same integer, provided no information used in `equals` comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  - If two objects are equal according to the `equals(Object)` method, then calling the `hashCode` method on each of the two objects must produce the same integer result.
  - It is not required that if two objects are unequal according to the `Object.equals(java.lang.Object)` method, then calling the `hashCode` method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables.

  As much as is reasonably practical, the hashCode method defined by class `Object` does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)

  Overrides:
    `hashCode` in class `Object`
  Returns:
    a hash code value for this object.
  See Also:
    `Object.equals(java.lang.Object)`, `Hashtable`

### equals

    public final boolean equals(byte[] bArray,
                                short offset,
                                byte length)
                         throws ArrayIndexOutOfBoundsException,
                                SecurityException

  Checks if the specified AID bytes in `bArray` are the same as those encapsulated in `this` `AID` object. The result is `true` if and only if the `bArray` argument is not `null` and the AID bytes encapsulated in `this` `AID` object are equal to the specified AID bytes in `bArray`.

  This method does not throw `NullPointerException`.

  Parameters:
    `bArray` - containing the AID bytes
    `offset` - within bArray to begin
    `length` - of AID bytes in bArray
  Returns:
    `true` if equal, `false` otherwise
  Throws:
    `SecurityException` - if the `bArray` array is not accessible in the caller's context
    `ArrayIndexOutOfBoundsException` - if the `offset` parameter or `length` parameter is negative or if `offset+length` is greater than the length of the `bArray` parameter

### partialEquals

    public final boolean partialEquals(byte[] bArray,
                                       short offset,
                                       byte length)
                                throws ArrayIndexOutOfBoundsException,
                                       SecurityException

  Checks if the specified partial AID byte sequence matches the first `length` bytes of the encapsulated AID bytes within `this` `AID` object. The result is `true` if and only if the `bArray` argument is not `null` and the input `length` is less than or equal to the length of the encapsulated AID bytes within `this` `AID` object and the specified bytes match.

  This method does not throw `NullPointerException`.

  Parameters:
    `bArray` - containing the partial AID byte sequence
    `offset` - within bArray to begin
    `length` - of partial AID bytes in bArray
  Returns:
    `true` if equal, `false` otherwise
  Throws:
    `SecurityException` - if the `bArray` array is not accessible in the caller's context
    `ArrayIndexOutOfBoundsException` - if the `offset` parameter or `length` parameter is negative or if `offset+length` is greater than the length of the `bArray` parameter

### RIDEquals

    public final boolean RIDEquals(AID otherAID)
                            throws SecurityException

  Checks if the RID (National Registered Application provider identifier) portion of the encapsulated AID bytes within the `otherAID` object matches that of `this` `AID` object. The first 5 bytes of an AID byte sequence is the RID. See ISO 7816-5 for details. The result is `true` if and only if the argument is not `null` and is an `AID` object that encapsulates the same RID bytes as `this` object.

  This method does not throw `NullPointerException`.

  Parameters:
    `otherAID` - the `AID` to compare against
  Returns:
    `true` if the RID bytes match, `false` otherwise
  Throws:
    `SecurityException` - if the `otherAID` object is not accessible in the caller's context

### getPartialBytes

    public final byte getPartialBytes(short aidOffset,
                                      byte[] dest,
                                      short oOffset,
                                      byte oLength)
                               throws NullPointerException,
                                      ArrayIndexOutOfBoundsException,
                                      SecurityException

  Called to get part of the AID bytes encapsulated within the `AID` object starting at the specified offset for the specified length.

  Parameters:
    `aidOffset` - offset within AID array to begin copying bytes
    `dest` - the destination byte array to copy the AID bytes into
    `oOffset` - offset within dest where the output bytes begin
    `oLength` - the length of bytes requested in `dest`. `0` implies a request to copy all remaining AID bytes.
  Returns:
    the actual length of the bytes returned in `dest`
  Throws:
    `SecurityException` - if the `dest` array is not accessible in the caller's context
    `NullPointerException` - if the `dest` parameter is `null`
    `ArrayIndexOutOfBoundsException` - if the `aidOffset` parameter is negative or greater than the length of the encapsulated AID bytes or the `oOffset` parameter is negative or `oOffset+length` of bytes requested is greater than the length of the `dest` array

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.