Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Renamed complete key to named key and add documentation #182

Merged
merged 1 commit into from
Oct 4, 2016
Merged

Renamed complete key to named key and add documentation #182

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/Datastore/DatastoreClient.php
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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