| <?php | |
| /* | |
| * Licensed to the Apache Software Foundation (ASF) under one or more | |
| * contributor license agreements. See the NOTICE file distributed with | |
| * this work for additional information regarding copyright ownership. | |
| * The ASF licenses this file to You under the Apache License, Version 2.0 | |
| * (the "License"); you may not use this file except in compliance with | |
| * the License. You may obtain a copy of the License at | |
| * | |
| * http://www.apache.org/licenses/LICENSE-2.0 | |
| * | |
| * Unless required by applicable law or agreed to in writing, software | |
| * distributed under the License is distributed on an "AS IS" BASIS, | |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
| * See the License for the specific language governing permissions and | |
| * limitations under the License. | |
| */ | |
| namespace Apache\Ignite\Cache; | |
| use Apache\Ignite\Type\ObjectType; | |
| use Apache\Ignite\Exception\ClientException; | |
| use Apache\Ignite\Query\Query; | |
| use Apache\Ignite\Query\CursorInterface; | |
| /** | |
| * Interface representing and providing access to Ignite cache. | |
| * | |
| * An instance of the class with this interface should be obtained via the methods of Ignite Client. | |
| * One instance of such a class provides access to one Ignite cache which is specified | |
| * during the instance obtaining and cannot be changed after that. | |
| * | |
| * There are three groups of methods in the cache interface: | |
| * - methods to configure the interface itself (optionally specify Ignite type for cache key and/or value) | |
| * - methods to operate with the cache using Key-Value Queries | |
| * - methods to operate with the cache using SQL and Scan Queries | |
| * | |
| */ | |
| interface CacheInterface | |
| { | |
| /** @name PeekMode | |
| * @anchor PeekMode | |
| * @{ | |
| */ | |
| /** | |
| * Peek mode ALL | |
| */ | |
| const PEEK_MODE_ALL = 0; | |
| /** | |
| * Peek mode NEAR | |
| */ | |
| const PEEK_MODE_NEAR = 1; | |
| /** | |
| * Peek mode PRIMARY | |
| */ | |
| const PEEK_MODE_PRIMARY = 2; | |
| /** | |
| * Peek mode BACKUP | |
| */ | |
| const PEEK_MODE_BACKUP = 3; | |
| /** @} */ // end of PeekMode | |
| /* Methods to configure the cache interface */ | |
| /** | |
| * Specifies a type of the cache key. | |
| * | |
| * Ignite client assumes that keys in all further operations with the cache | |
| * will have the Ignite type specified by this method. | |
| * Eg. the client will convert keys provided as input parameters of the Key-Value or SQL operations | |
| * to the specified Ignite object type before sending the keys to a server. | |
| * | |
| * By default a type of the cache key is not specified (null). | |
| * | |
| * If the type is not specified then during operations Ignite client | |
| * will do automatic mapping between some of the PHP types and Ignite object types - | |
| * according to the mapping table defined in the description of the ObjectType class. | |
| * | |
| * @param int|ObjectType|null $type type of the keys in the cache: | |
| * - either a type code of primitive (simple) type | |
| * - or an instance of class representing non-primitive (composite) type | |
| * - or null (means the type is not specified). | |
| * | |
| * @return CacheInterface the same instance of the class. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function setKeyType($type): CacheInterface; | |
| /** | |
| * Specifies a type of the cache value. | |
| * | |
| * Ignite client assumes that values in all further operations with the cache | |
| * will have the Ignite type specified by this method. | |
| * Eg. the client will convert values provided as input parameters of the Key-Value or SQL operations | |
| * to the specified Ignite object type before sending the values to a server. | |
| * | |
| * By default a type of the cache value is not specified (null). | |
| * | |
| * If the type is not specified then during operations Ignite client | |
| * will do automatic mapping between some of the PHP types and Ignite object types - | |
| * according to the mapping table defined in the description of the ObjectType class. | |
| * | |
| * @param int|ObjectType|null $type type of the values in the cache: | |
| * - either a type code of primitive (simple) type (@ref PrimitiveTypeCodes) | |
| * - or an instance of class representing non-primitive (composite) type | |
| * - or null (means the type is not specified). | |
| * | |
| * @return CacheInterface the same instance of the class. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function setValueType($type): CacheInterface; | |
| /* Methods to operate with the cache using Key-Value Queries */ | |
| /** | |
| * Retrieves a value associated with the specified key from the cache. | |
| * | |
| * @param mixed $key key. | |
| * | |
| * @return mixed value associated with the specified key, or null if it does not exist. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function get($key); | |
| /** | |
| * Retrieves entries associated with the specified keys from the cache. | |
| * | |
| * @param array $keys keys. | |
| * | |
| * @return array the retrieved entries (key-value pairs) of CacheEntry. | |
| * Entries with the keys which do not exist in the cache are not included into the array. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function getAll(array $keys): array; | |
| /** | |
| * Associates the specified value with the specified key in the cache. | |
| * | |
| * Overwrites the previous value if the key exists in the cache, | |
| * otherwise creates new entry (key-value pair). | |
| * | |
| * @param mixed $key key | |
| * @param mixed $value value to be associated with the specified key. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function put($key, $value): void; | |
| /** | |
| * Associates the specified values with the specified keys in the cache. | |
| * | |
| * Overwrites the previous value if a key exists in the cache, | |
| * otherwise creates new entry (key-value pair). | |
| * | |
| * @param array $entries entries (key-value pairs) of CacheEntry to be put into the cache. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function putAll(array $entries): void; | |
| /** | |
| * Checks if the specified key exists in the cache. | |
| * | |
| * @param mixed $key key to check. | |
| * | |
| * @return bool true if the key exists, false otherwise. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function containsKey($key): bool; | |
| /** | |
| * Checks if all the specified keys exist in the cache. | |
| * | |
| * @param array $keys keys to check. | |
| * | |
| * @return bool true if all the keys exist, | |
| * false if at least one of the keys does not exist in the cache. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function containsKeys(array $keys): bool; | |
| /** | |
| * Associates the specified value with the specified key in the cache | |
| * and returns the previous associated value, if any. | |
| * | |
| * Overwrites the previous value if the key exists in the cache, | |
| * otherwise creates new entry (key-value pair). | |
| * | |
| * @param mixed $key key. | |
| * @param mixed $value value to be associated with the specified key. | |
| * | |
| * @return mixed the previous value associated with the specified key, or null if it did not exist. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function getAndPut($key, $value); | |
| /** | |
| * Associates the specified value with the specified key in the cache | |
| * and returns the previous associated value, if the key exists in the cache. | |
| * Otherwise does nothing and returns null. | |
| * | |
| * @param mixed $key key. | |
| * @param mixed $value value to be associated with the specified key. | |
| * | |
| * @return mixed the previous value associated with the specified key, or null if it did not exist. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function getAndReplace($key, $value); | |
| /** | |
| * Removes the cache entry with the specified key and returns the last associated value, if any. | |
| * | |
| * @param mixed $key key of the entry to be removed. | |
| * | |
| * @return mixed the last value associated with the specified key, or null if it did not exist. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function getAndRemove($key); | |
| /** | |
| * Creates new entry (key-value pair) if the specified key does not exist in the cache. | |
| * Otherwise does nothing. | |
| * | |
| * @param mixed $key key. | |
| * @param mixed $value value to be associated with the specified key. | |
| * | |
| * @return true if the operation has been done, false otherwise. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function putIfAbsent($key, $value): bool; | |
| /** | |
| * Creates new entry (key-value pair) if the specified key does not exist in the cache. | |
| * Otherwise returns the current value associated with the existing key. | |
| * | |
| * @param mixed $key key. | |
| * @param mixed $value value to be associated with the specified key. | |
| * | |
| * @return mixed the current value associated with the key if it already exists in the cache, | |
| * null if the new entry is created. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function getAndPutIfAbsent($key, $value); | |
| /** | |
| * Associates the specified value with the specified key, if the key exists in the cache. | |
| * Otherwise does nothing. | |
| * | |
| * @param mixed $key key. | |
| * @param mixed $value value to be associated with the specified key. | |
| * | |
| * @return bool true if the operation has been done, false otherwise. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function replace($key, $value): bool; | |
| /** | |
| * Associates the new value with the specified key, if the key exists in the cache | |
| * and the current value equals to the provided one. | |
| * Otherwise does nothing. | |
| * | |
| * @param mixed $key key. | |
| * @param mixed $value value to be compared with the current value associated with the specified key. | |
| * @param mixed $newValue new value to be associated with the specified key. | |
| * | |
| * @return bool true if the operation has been done, false otherwise. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function replaceIfEquals($key, $value, $newValue): bool; | |
| /** | |
| * Removes all entries from the cache, without notifying listeners and cache writers. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function clear(): void; | |
| /** | |
| * Removes entry with the specified key from the cache, without notifying listeners and cache writers. | |
| * | |
| * @param mixed $key key to be removed. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function clearKey($key): void; | |
| /** | |
| * Removes entries with the specified keys from the cache, without notifying listeners and cache writers. | |
| * | |
| * @param array $keys keys to be removed. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function clearKeys($keys): void; | |
| /** | |
| * Removes entry with the specified key from the cache, notifying listeners and cache writers. | |
| * | |
| * @param mixed $key key to be removed. | |
| * | |
| * @return bool true if the operation has been done, false otherwise. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function removeKey($key): bool; | |
| /** | |
| * Removes entry with the specified key from the cache, if the current value equals to the provided one. | |
| * Notifies listeners and cache writers. | |
| * | |
| * @param mixed $key key to be removed. | |
| * @param mixed $value value to be compared with the current value associated with the specified key. | |
| * | |
| * @return bool true if the operation has been done, false otherwise. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function removeIfEquals($key, $value): bool; | |
| /** | |
| * Removes entries with the specified keys from the cache, notifying listeners and cache writers. | |
| * | |
| * @param array $keys keys to be removed. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function removeKeys($keys): void; | |
| /** | |
| * Removes all entries from the cache, notifying listeners and cache writers. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function removeAll(): void; | |
| /** | |
| * Returns the number of the entries in the cache. | |
| * | |
| * @param int ...$peekModes peek modes, values from @ref PeekMode constants. | |
| * | |
| * @return int the number of the entries in the cache. | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function getSize(int ...$peekModes): int; | |
| /* Methods to operate with the cache using SQL and Scan Queries */ | |
| /** | |
| * Starts an SQL, SQL Fields or Scan query operation. | |
| * | |
| * @param Query $query query to be executed. | |
| * | |
| * @return CursorInterface new instance of the class with interface representing a cursor | |
| * to obtain the results of the query operation: | |
| * - SqlFieldsCursorInterface in case of SqlFieldsQuery query | |
| * - CursorInterface in case of other types of query | |
| * | |
| * @throws ClientException if error. | |
| */ | |
| public function query(Query $query): CursorInterface; | |
| } |