com.google.appengine.api.datastore

## Class KeyFactory

- java.lang.Object
- - com.google.appengine.api.datastore.KeyFactory

-     public class KeyFactory
      extends java.lang.Object

  This class enables direct creation of `Key` objects, both in the root entity group (no parent) and as the child of a given parent. Keys can also be created indirectly by putting named Entities into the datastore, which will allocate a new key. See `Entity.Entity(String, String)` for details.

  This class also has methods for encoding and decoding `Key` objects to and from strings. Clients should not make any assumptions about the encoding format, except that it is a websafe string that does not need to be quoted when used in HTML or in URLs.

  See Also:
    `Entity`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `KeyFactory.Builder` Helper class that aids in the construction of `Keys` with ancestors.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Key` | `createKey(Key parent, java.lang.String kind, long id)` Creates a new `Key` with the provided parent from its kind and ID.
    `static Key` | `createKey(Key parent, java.lang.String kind, java.lang.String name)` Creates a new `Key` with the provided parent from its kind and name.
    `static Key` | `createKey(java.lang.String kind, long id)` Creates a new `Key` having no parent from its kind and ID.
    `static Key` | `createKey(java.lang.String kind, java.lang.String name)` Creates a new `Key` having no parent from its kind and name.
    `static java.lang.String` | `createKeyString(Key parent, java.lang.String kind, long id)` Shorthand for invoking `keyToString(Key)` on the result of `createKey(Key, String, long)`
    `static java.lang.String` | `createKeyString(Key parent, java.lang.String kind, java.lang.String name)` Shorthand for invoking `keyToString(Key)` on the result of `createKey(Key, String, String)`
    `static java.lang.String` | `createKeyString(java.lang.String kind, long id)` Shorthand for invoking `keyToString(Key)` on the result of `createKey(String, long)`
    `static java.lang.String` | `createKeyString(java.lang.String kind, java.lang.String name)` Shorthand for invoking `keyToString(Key)` on the result of `createKey(String, String)`
    `static java.lang.String` | `keyToString(Key key)` Converts a `Key` into a websafe string.
    `static Key` | `stringToKey(java.lang.String encoded)` Converts a `String`-representation of a `Key` into the `Key` instance it represents.

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

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

- - ### Method Detail

    - #### createKey

          public static Key createKey(java.lang.String kind,
                      long id)

      Creates a new `Key` having no parent from its kind and ID.
      Parameters:
        `kind` - the kind of the key to create
        `id` - the numeric identifier of the key in `kind`, unique across all root entities of this kind, must not be zero

    - #### createKey

          public static Key createKey(Key parent,
                      java.lang.String kind,
                      long id)

      Creates a new `Key` with the provided parent from its kind and ID.
      Parameters:
        `parent` - the parent of the key to create, can be `null`
        `kind` - the kind of the key to create
        `id` - the numeric identifier of the key in `kind`, unique across all entities of this kind with the same parent, must not be zero

    - #### createKey

          public static Key createKey(java.lang.String kind,
                      java.lang.String name)

      Creates a new `Key` having no parent from its kind and name.
      Parameters:
        `kind` - the kind of the key to create
        `name` - the name of the key in `kind`, as an arbitrary string unique across all root entities of this `kind`

    - #### createKey

          public static Key createKey(Key parent,
                      java.lang.String kind,
                      java.lang.String name)

      Creates a new `Key` with the provided parent from its kind and name.
      Parameters:
        `parent` - the parent of the key to create, can be `null`
        `kind` - the kind of the key to create
        `name` - the name of the key in `kind`, as an arbitrary string unique across all entities of this `kind` with the same parent

    - #### createKeyString

          public static java.lang.String createKeyString(java.lang.String kind,
                                         long id)

      Shorthand for invoking `keyToString(Key)` on the result of `createKey(String, long)`
      Parameters:
        `kind` - the kind of the key to create
        `id` - the numeric identifier of the key in `kind`, unique across all root entities of this kind, must not be zero
      Returns:
        A websafe `String` representation of the `Key` that was created

    - #### createKeyString

          public static java.lang.String createKeyString(Key parent,
                                         java.lang.String kind,
                                         long id)

      Shorthand for invoking `keyToString(Key)` on the result of `createKey(Key, String, long)`
      Parameters:
        `parent` - the parent of the key to create, can be `null`.
        `kind` - the kind of the key to create
        `id` - the numeric identifier of the key in `kind`, unique across entities of this kind with the same parent, must not be zero
      Returns:
        A websafe `String` representation of the `Key` that was created

    - #### createKeyString

          public static java.lang.String createKeyString(java.lang.String kind,
                                         java.lang.String name)

      Shorthand for invoking `keyToString(Key)` on the result of `createKey(String, String)`
      Parameters:
        `kind` - the kind of the key to create
        `name` - the name of the key in `kind`, as an arbitrary string unique across root entities of this `kind`
      Returns:
        A websafe `String` representation of the `Key` that was created

    - #### createKeyString

          public static java.lang.String createKeyString(Key parent,
                                         java.lang.String kind,
                                         java.lang.String name)

      Shorthand for invoking `keyToString(Key)` on the result of `createKey(Key, String, String)`
      Parameters:
        `parent` - the parent of the key to create, can be `null`.
        `kind` - the kind of the key to create
        `name` - the name of the key in `kind`, as an arbitrary string unique across entities of this `kind` with the same parent
      Returns:
        A websafe `String` representation of the `Key` that was created

    - #### keyToString

          public static java.lang.String keyToString(Key key)

      Converts a `Key` into a websafe string. For example, this string can safely be used as an URL parameter embedded in a HTML document. Note that `key.equals(KeyFactory.stringToKey(KeyFactory.keyToString(key))` should evaluate to `true`.
      Parameters:
        `key` - The `Key` to convert to a `String`.
      Returns:
        A websafe `String` representation of the provided `String`.
      Throws:
        `java.lang.IllegalArgumentException` - If the specified `Key` is incomplete.

    - #### stringToKey

          public static Key stringToKey(java.lang.String encoded)

      Converts a `String`-representation of a `Key` into the `Key` instance it represents. Note that `str.equals(KeyFactory.keyToString(KeyFactory.stringToKey(str))` should evaluate to `true` for all strings returned by `keyToString(com.google.appengine.api.datastore.Key)`.
      Parameters:
        `encoded` - The `String` representation of a `Key`.
      Returns:
        The `Key` that the given `String` represents.
      Throws:
        `java.lang.IllegalArgumentException` - If the string cannot be parsed.