Package org.bouncycastle.openpgp

## Class PGPSecretKeyRingCollection

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

- All Implemented Interfaces:
    `java.lang.Iterable<PGPSecretKeyRing>`, `org.bouncycastle.util.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 | Description
    --- | ---
    `PGPSecretKeyRingCollection​(byte[] encoding, KeyFingerPrintCalculator fingerPrintCalculator)` |
    `PGPSecretKeyRingCollection​(java.io.InputStream in, KeyFingerPrintCalculator fingerPrintCalculator)` | Build a PGPSecretKeyRingCollection from the passed in input stream.
    `PGPSecretKeyRingCollection​(java.util.Collection<PGPSecretKeyRing> collection)` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | 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`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach, spliterator`

- - ### 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 parsing 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>`
      Specified by:
        `iterator` in interface `org.bouncycastle.util.Iterable<PGPSecretKeyRing>`