| <?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; |
| } |