Skip to content

Commit

Permalink
Renamed complete key to named key and add documentation (#182)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jdpedrie @dwsupplee
jdpedrie authored and dwsupplee committed Oct 4, 2016
1 parent 3cf8be5 commit f7c3831
Show file tree
Hide file tree
Showing 5 changed files with 49 additions and 28 deletions.
2 changes: 1 addition & 1 deletion src/Datastore/DatastoreClient.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -226,7 +226,7 @@ public function keys($kind, array $options = [])
*
* Entities are created with a Datastore Key, or by specifying a Kind. Kinds
* are only allowed for insert operations. For any other case, you must
* specify a complete key. If a kind is given, an ID will be automatically
* specify a named key. If a kind is given, an ID will be automatically
* allocated for the entity upon insert. Additionally, if your entity
* requires a complex key elementPath, you must create the key separately.
*
Expand Down
39 changes: 30 additions & 9 deletions src/Datastore/Key.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,24 @@
*
* Keys are unique identifiers for entities.
*
* Keys may be considered either "named" or "incomplete". A named Key is one in
* which each element of the Key path specify a Kind and a Name or ID. An
* incomplete Key omits the Name or ID from the final path element.
*
* Named Keys are required for any lookup, update, upsert or delete operations.
* They may also be used for inserting records, so long as you are certain that
* the identifier is available in Datastore.
*
* Incomplete Keys may be used for inserting records into Datastore. When an
* incomplete Key is used, Datastore will allocate an ID before inserting.
*
* Incomplete Keys are useful for guaranteeing the availability of an identifier
* without requiring an additional operation to check whether a given name or ID
* is available.
*
* Key state can be checked by calling `Key::state()`. The return will be one of
* `Key::STATE_NAMED` or `Key::STATE_INCOMPLETE`.
*
* Example:
* ```
* use Google\Cloud\ServiceBuilder;
Expand Down Expand Up @@ -62,9 +80,12 @@ class Key implements JsonSerializable
const TYPE_NAME = 'name';
const TYPE_ID = 'id';

const STATE_COMPLETE = 'complete';
const STATE_NAMED = 'named';
const STATE_INCOMPLETE = 'incomplete';

// Kept for backwards compatability
const STATE_COMPLETE = self::STATE_NAMED;

/**
* @var string
*/
Expand Down Expand Up @@ -132,7 +153,7 @@ public function __construct($projectId, array $options = [])
*/
public function pathElement($kind, $identifier = null, $identifierType = null)
{
if (!empty($this->path) && $this->state() !== Key::STATE_COMPLETE) {
if (!empty($this->path) && $this->state() !== Key::STATE_NAMED) {
throw new InvalidArgumentException(
'Cannot add pathElement because the previous element is missing an id or name'
);
Expand Down Expand Up @@ -188,7 +209,7 @@ public function ancestor($kind, $identifier, $identifierType = null)
*/
public function ancestorKey(Key $key)
{
if ($key->state() !== self::STATE_COMPLETE) {
if ($key->state() !== self::STATE_NAMED) {
throw new InvalidArgumentException('Cannot use an incomplete key as an ancestor');
}

Expand All @@ -200,9 +221,9 @@ public function ancestorKey(Key $key)
}

/**
* Check if the Key is considered Complete or Incomplete.
* Check if the Key is considered Named or Incomplete.
*
* Use `Key::STATE_COMPLETE` and `Key::STATE_INCOMPLETE` to check value.
* Use `Key::STATE_NAMED` and `Key::STATE_INCOMPLETE` to check value.
*
* Example:
* ```
Expand All @@ -216,12 +237,12 @@ public function ancestorKey(Key $key)
* ```
*
* ```
* // A complete key has a kind and an identifier on each path element.
* // A named key has a kind and an identifier on each path element.
* $key = $datastore->key('parent', 1234)
* ->pathElement('child', 4321);
*
* if ($key->state() === Key::STATE_COMPLETE) {
* echo 'Key is complete!';
* if ($key->state() === Key::STATE_NAMED) {
* echo 'Key is named!';
* }
* ```
*
Expand All @@ -231,7 +252,7 @@ public function state()
{
$end = $this->pathEnd();
return (isset($end['id']) || isset($end['name']))
? self::STATE_COMPLETE
? self::STATE_NAMED
: self::STATE_INCOMPLETE;
}

Expand Down
8 changes: 4 additions & 4 deletions src/Datastore/Operation.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ public function keys($kind, array $options = [])
*
* Entities are created with a Datastore Key, or by specifying a Kind. Kinds
* are only allowed for insert operations. For any other case, you must
* specify a complete key. If a kind is given, an ID will be automatically
* specify a named key. If a kind is given, an ID will be automatically
* allocated for the entity upon insert. Additionally, if your entity
* requires a complex key elementPath, you must create the key separately.
*
Expand Down Expand Up @@ -251,7 +251,7 @@ public function entity($key, array $entity = [], array $options = [])
public function allocateIds(array $keys, array $options = [])
{
// Validate the given keys. First check types, then state of each.
// The API will throw a 400 if the key is complete, but it's an easy
// The API will throw a 400 if the key is named, but it's an easy
// check we can handle before going to the API to save a request.
// @todo replace with json schema
$this->validateBatch($keys, Key::class, function ($key) {
Expand Down Expand Up @@ -313,7 +313,7 @@ public function lookup(array $keys, array $options = [])
];

$this->validateBatch($keys, Key::class, function ($key) {
if ($key->state() !== Key::STATE_COMPLETE) {
if ($key->state() !== Key::STATE_NAMED) {
throw new InvalidArgumentException(sprintf(
'Given $key is in an invalid state. Can only lookup records when given a complete key. ' .
'Given path was %s',
Expand Down Expand Up @@ -451,7 +451,7 @@ public function commit(array $options = [])
/**
* Patch any incomplete keys in the given array of entities
*
* Any incomplete keys will be allocated an ID. Complete keys in the input
* Any incomplete keys will be allocated an ID. Named keys in the input
* will remain unchanged.
*
* @param Entity[] $entities A list of entities
Expand Down
6 changes: 3 additions & 3 deletions tests/Datastore/KeyTest.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ public function testAncestorKey()

$ancestor = $this->prophesize(Key::class);
$ancestor->path()->willReturn($ancestorPath);
$ancestor->state()->willReturn(Key::STATE_COMPLETE);
$ancestor->state()->willReturn(Key::STATE_NAMED);

$key = new Key('foo', [
'path' => [
Expand Down Expand Up @@ -187,15 +187,15 @@ public function testJsonSerialize()
$this->assertEquals($key->jsonSerialize(), $key->keyObject());
}

public function testStateComplete()
public function testStateNamed()
{
$key = new Key('foo', [
'path' => [
['kind' => 'foo', 'id' => 1]
]
]);

$this->assertEquals($key->state(), key::STATE_COMPLETE);
$this->assertEquals($key->state(), key::STATE_NAMED);
}

public function testStateIncomplete()
Expand Down
22 changes: 11 additions & 11 deletions tests/Datastore/OperationTest.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -166,14 +166,14 @@ public function testAllocateIds()

$res = $this->operation->allocateIds($keys);

$this->assertEquals($res[0]->state(), Key::STATE_COMPLETE);
$this->assertEquals($res[0]->state(), Key::STATE_NAMED);
$this->assertEquals($res[0]->path()[0]['id'], '1');
}

/**
* @expectedException InvalidArgumentException
*/
public function testAllocateIdsCompleteKey()
public function testAllocateIdsNamedKey()
{
$keys = [
$this->operation->key('foo', 'Bar')
Expand Down Expand Up @@ -450,8 +450,8 @@ public function testAllocateIdsToEntities()
$this->assertInstanceOf(Entity::class, $res[0]);
$this->assertInstanceOf(Entity::class, $res[1]);

$this->assertEquals($res[0]->key()->state(), Key::STATE_COMPLETE);
$this->assertEquals($res[1]->key()->state(), Key::STATE_COMPLETE);
$this->assertEquals($res[0]->key()->state(), Key::STATE_NAMED);
$this->assertEquals($res[1]->key()->state(), Key::STATE_NAMED);
}

public function testMutate()
Expand Down Expand Up @@ -559,7 +559,7 @@ public function testMapEntityResult()
$this->operation->setConnection($this->connection->reveal());

$k = $this->prophesize(Key::class);
$k->state()->willReturn(Key::STATE_COMPLETE);
$k->state()->willReturn(Key::STATE_NAMED);

$entity = $this->operation->lookup([$k->reveal()]);
$this->assertInstanceOf(Entity::class, $entity['found'][0]);
Expand All @@ -581,7 +581,7 @@ public function testMapEntityResultWithoutProperties()
$this->operation->setConnection($this->connection->reveal());

$k = $this->prophesize(Key::class);
$k->state()->willReturn(Key::STATE_COMPLETE);
$k->state()->willReturn(Key::STATE_NAMED);

$entity = $this->operation->lookup([$k->reveal()]);
$this->assertInstanceOf(Entity::class, $entity['found'][0]);
Expand All @@ -602,7 +602,7 @@ public function testMapEntityResultArrayOfClassNames()
$this->operation->setConnection($this->connection->reveal());

$k = $this->prophesize(Key::class);
$k->state()->willReturn(Key::STATE_COMPLETE);
$k->state()->willReturn(Key::STATE_NAMED);

$entity = $this->operation->lookup([$k->reveal()], [
'className' => [
Expand All @@ -628,7 +628,7 @@ public function testMapEntityResultArrayOfClassNamesMissingKindMapItem()
$this->operation->setConnection($this->connection->reveal());

$k = $this->prophesize(Key::class);
$k->state()->willReturn(Key::STATE_COMPLETE);
$k->state()->willReturn(Key::STATE_NAMED);

$entity = $this->operation->lookup([$k->reveal()], [
'className' => [
Expand All @@ -649,7 +649,7 @@ public function testTransactionInReadOptions()
$this->operation->setConnection($this->connection->reveal());

$k = $this->prophesize(Key::class);
$k->state()->willReturn(Key::STATE_COMPLETE);
$k->state()->willReturn(Key::STATE_NAMED);
$this->operation->lookup([$k->reveal()], [
'transaction' => '1234'
]);
Expand All @@ -667,7 +667,7 @@ public function testNonTransactionalReadOptions()
$this->operation->setConnection($this->connection->reveal());

$k = $this->prophesize(Key::class);
$k->state()->willReturn(Key::STATE_COMPLETE);
$k->state()->willReturn(Key::STATE_NAMED);
$this->operation->lookup([$k->reveal()]);
}

Expand All @@ -683,7 +683,7 @@ public function testReadConsistencyInReadOptions()
$this->operation->setConnection($this->connection->reveal());

$k = $this->prophesize(Key::class);
$k->state()->willReturn(Key::STATE_COMPLETE);
$k->state()->willReturn(Key::STATE_NAMED);
$this->operation->lookup([$k->reveal()], [
'readConsistency' => 'test'
]);
Expand Down

0 comments on commit f7c3831

Please sign in to comment.