# KeyFactory
Date: 2012-02-24

## com.google.appengine.api.datastore
Class KeyFactory

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

    public class KeyFactory

extends java.lang.Object

Allows you to create arbitrary `Key` objects in the root entity group group (no parent).

Also allows you to encode `Key` objects to and decode them from strings. Clients should not make any assumptions about this return value, except that it is a websafe string that does not need to be quoted when used in HTML or in URLs.

Nested Class Summary
`static class` `KeyFactory.Builder` Helper class that aids in the construction of `Keys` with ancestors.

Method Summary
`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, long)`
`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, long)`
`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, long)`

  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, long)`

  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.