PGPSecretKeyRingCollection
Date: 2016-06-23

org.bouncycastle.openpgp

## Class PGPSecretKeyRingCollection

- java.lang.Object
- - org.bouncycastle.openpgp.PGPSecretKeyRingCollection

- All Implemented Interfaces:
    java.lang.Iterable<PGPSecretKeyRing>
  Direct Known Subclasses:
    BcPGPSecretKeyRingCollection, JcaPGPSecretKeyRingCollection

      public class PGPSecretKeyRingCollection
      extends java.lang.Object
      implements org.bouncycastle.util.Iterable<PGPSecretKeyRing>

  Often a PGP key ring file is made up of a succession of master/sub-key key rings. If you want to read an entire secret key file in one hit this is the class for you.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `PGPSecretKeyRingCollection(byte[] encoding, KeyFingerPrintCalculator fingerPrintCalculator)`
    `PGPSecretKeyRingCollection(java.util.Collection<PGPSecretKeyRing> collection)`
    `PGPSecretKeyRingCollection(java.io.InputStream in, KeyFingerPrintCalculator fingerPrintCalculator)` Build a PGPSecretKeyRingCollection from the passed in input stream.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static PGPSecretKeyRingCollection` | `addSecretKeyRing(PGPSecretKeyRingCollection ringCollection, PGPSecretKeyRing secretKeyRing)` Return a new collection object containing the contents of the passed in collection and the passed in secret key ring.
    `boolean` | `contains(long keyID)` Return true if a key matching the passed in key ID is present, false otherwise.
    `void` | `encode(java.io.OutputStream outStream)`
    `byte[]` | `getEncoded()`
    `java.util.Iterator<PGPSecretKeyRing>` | `getKeyRings()` return the secret key rings making up this collection.
    `java.util.Iterator<PGPSecretKeyRing>` | `getKeyRings(java.lang.String userID)` Return an iterator of the key rings associated with the passed in userID.
    `java.util.Iterator<PGPSecretKeyRing>` | `getKeyRings(java.lang.String userID, boolean matchPartial)` Return an iterator of the key rings associated with the passed in userID.
    `java.util.Iterator<PGPSecretKeyRing>` | `getKeyRings(java.lang.String userID, boolean matchPartial, boolean ignoreCase)` Return an iterator of the key rings associated with the passed in userID.
    `PGPSecretKey` | `getSecretKey(long keyID)` Return the PGP secret key associated with the given key id.
    `PGPSecretKeyRing` | `getSecretKeyRing(long keyID)` Return the secret key ring which contains the key referred to by keyID.
    `java.util.Iterator<PGPSecretKeyRing>` | `iterator()` Support method for Iterable where available.
    `static PGPSecretKeyRingCollection` | `removeSecretKeyRing(PGPSecretKeyRingCollection ringCollection, PGPSecretKeyRing secretKeyRing)` Return a new collection object containing the contents of this collection with the passed in secret key ring removed.
    `int` | `size()` Return the number of rings in this collection.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### PGPSecretKeyRingCollection

          public PGPSecretKeyRingCollection(byte[] encoding,
                                    KeyFingerPrintCalculator fingerPrintCalculator)
                                     throws java.io.IOException,
                                            PGPException

      Throws:
        `java.io.IOException`
        `PGPException`

    - #### PGPSecretKeyRingCollection

          public PGPSecretKeyRingCollection(java.io.InputStream in,
                                    KeyFingerPrintCalculator fingerPrintCalculator)
                                     throws java.io.IOException,
                                            PGPException

      Build a PGPSecretKeyRingCollection from the passed in input stream.
      Parameters:
        `in` - input stream containing data
      Throws:
        `java.io.IOException` - if a problem parsinh the base stream occurs
        `PGPException` - if an object is encountered which isn't a PGPSecretKeyRing

    - #### PGPSecretKeyRingCollection

          public PGPSecretKeyRingCollection(java.util.Collection<PGPSecretKeyRing> collection)
                                     throws java.io.IOException,
                                            PGPException

      Throws:
        `java.io.IOException`
        `PGPException`

  - ### Method Detail

    - #### size

          public int size()

      Return the number of rings in this collection.
      Returns:
        size of the collection

    - #### getKeyRings

          public java.util.Iterator<PGPSecretKeyRing> getKeyRings()

      return the secret key rings making up this collection.

    - #### getKeyRings

          public java.util.Iterator<PGPSecretKeyRing> getKeyRings(java.lang.String userID)
                                                           throws PGPException

      Return an iterator of the key rings associated with the passed in userID.
      Parameters:
        `userID` - the user ID to be matched.
      Returns:
        an iterator (possibly empty) of key rings which matched.
      Throws:
        `PGPException`

    - #### getKeyRings

          public java.util.Iterator<PGPSecretKeyRing> getKeyRings(java.lang.String userID,
                                                         boolean matchPartial)
                                                           throws PGPException

      Return an iterator of the key rings associated with the passed in userID.

      Parameters:
        `userID` - the user ID to be matched.
        `matchPartial` - if true userID need only be a substring of an actual ID string to match.
      Returns:
        an iterator (possibly empty) of key rings which matched.
      Throws:
        `PGPException`

    - #### getKeyRings

          public java.util.Iterator<PGPSecretKeyRing> getKeyRings(java.lang.String userID,
                                                         boolean matchPartial,
                                                         boolean ignoreCase)
                                                           throws PGPException

      Return an iterator of the key rings associated with the passed in userID.

      Parameters:
        `userID` - the user ID to be matched.
        `matchPartial` - if true userID need only be a substring of an actual ID string to match.
        `ignoreCase` - if true case is ignored in user ID comparisons.
      Returns:
        an iterator (possibly empty) of key rings which matched.
      Throws:
        `PGPException`

    - #### getSecretKey

          public PGPSecretKey getSecretKey(long keyID)
                                    throws PGPException

      Return the PGP secret key associated with the given key id.
      Parameters:
        `keyID` -
      Returns:
        the secret key
      Throws:
        `PGPException`

    - #### getSecretKeyRing

          public PGPSecretKeyRing getSecretKeyRing(long keyID)
                                            throws PGPException

      Return the secret key ring which contains the key referred to by keyID.
      Parameters:
        `keyID` -
      Returns:
        the secret key ring
      Throws:
        `PGPException`

    - #### contains

          public boolean contains(long keyID)
                           throws PGPException

      Return true if a key matching the passed in key ID is present, false otherwise.
      Parameters:
        `keyID` - key ID to look for.
      Returns:
        true if keyID present, false otherwise.
      Throws:
        `PGPException`

    - #### getEncoded

          public byte[] getEncoded()
                            throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### encode

          public void encode(java.io.OutputStream outStream)
                      throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### addSecretKeyRing

          public static PGPSecretKeyRingCollection addSecretKeyRing(PGPSecretKeyRingCollection ringCollection,
                                                    PGPSecretKeyRing secretKeyRing)

      Return a new collection object containing the contents of the passed in collection and the passed in secret key ring.
      Parameters:
        `ringCollection` - the collection the ring to be added to.
        `secretKeyRing` - the key ring to be added.
      Returns:
        a new collection merging the current one with the passed in ring.
      Throws:
        `java.lang.IllegalArgumentException` - if the keyID for the passed in ring is already present.

    - #### removeSecretKeyRing

          public static PGPSecretKeyRingCollection removeSecretKeyRing(PGPSecretKeyRingCollection ringCollection,
                                                       PGPSecretKeyRing secretKeyRing)

      Return a new collection object containing the contents of this collection with the passed in secret key ring removed.
      Parameters:
        `ringCollection` - the collection the ring to be removed from.
        `secretKeyRing` - the key ring to be removed.
      Returns:
        a new collection merging the current one with the passed in ring.
      Throws:
        `java.lang.IllegalArgumentException` - if the keyID for the passed in ring is not present.

    - #### iterator

          public java.util.Iterator<PGPSecretKeyRing> iterator()

      Support method for Iterable where available.
      Specified by:
        `iterator` in interface `java.lang.Iterable<PGPSecretKeyRing>`