001package com.nimbusds.infinispan.persistence.sql;
002
003
004import java.util.Collection;
005
006import com.nimbusds.infinispan.persistence.common.InfinispanEntry;
007import com.nimbusds.infinispan.persistence.sql.config.SQLStoreConfiguration;
008import org.jooq.Condition;
009import org.jooq.Record;
010import org.jooq.SQLDialect;
011
012
013/**
014 * Interface for transforming between Infinispan entries (key / value pair and
015 * metadata) and a corresponding SQL record. Implementations must be
016 * thread-safe.
017 *
018 * <p>To specify an entry transformer for a given Infinispan cache that is
019 * backed by an SQL store, provide its class name to the
020 * {@link SQLStoreConfiguration store configuration}.
021 */
022public interface SQLRecordTransformer<K,V> {
023        
024        
025        /**
026         * SQL transformer initialisation parameters.
027         */
028        interface InitParameters {
029                
030                
031                /**
032                 * Returns the configured SQL dialect.
033                 *
034                 * @return The SQL dialect.
035                 */
036                SQLDialect sqlDialect();
037        }
038        
039        
040        /**
041         * Initialises the SQL transformer.
042         *
043         * @param initParams The initialisation parameters.
044         */
045        void init(final InitParameters initParams);
046        
047        
048        /**
049         * Returns the SQL statement to create a table for the entries.
050         * Typically required on SQL store startup if the underlying table
051         * doesn't exist yet. The statement must be aware of the SQL dialect of
052         * the {@link #init configured} database.
053         *
054         * @return The SQL create table statement.
055         */
056        String getCreateTableStatement();
057        
058        
059        /**
060         * Returns the associated SQL table name.
061         *
062         * @return The table name.
063         */
064        String getTableName();
065        
066        
067        /**
068         * Resolves the SQL selection conditions for the specified Infinispan
069         * entry key.
070         *
071         * @param key The Infinispan entry key. Not {@code null}.
072         *
073         * @return One or more WHERE conditions.
074         */
075        Collection<Condition> resolveSelectionConditions(final K key);
076        
077
078        /**
079         * Transforms the specified Infinispan entry (key / value pair with
080         * optional metadata) to an SQL record ready to be written.
081         *
082         * <p>Example:
083         *
084         * <ul>
085         *     <li>Key: cae7t
086         *     <li>Value: Java POJO with fields {@code uid=cae7t},
087         *         {@code givenName=Alice}, {@code surname=Adams} and
088         *         {@code email=alice@wonderland.net}.
089         *     <li>Metadata: Specifies the entry expiration and other
090         *         properties.
091         * </ul>
092         *
093         * <p>Resulting SQL record:</p>
094         *
095         * <pre>
096         * uid: cae7t (key)
097         * surname: Adams
098         * given_name: Alice
099         * email: alice@wonderland.net
100         * </pre>
101         *
102         * @param infinispanEntry The Infinispan entry. Not {@code null}.
103         *
104         * @return The SQL record.
105         */
106        SQLRecord toSQLRecord(final InfinispanEntry<K,V> infinispanEntry);
107
108
109        /**
110         * Transforms the specified SQL record to an Infinispan entry (key /
111         * value / metadata triple).
112         *
113         * <p>Example:
114         *
115         * <p>SQL record:</p>
116         *
117         * <pre>
118         * uid: cae7t
119         * surname: Adams
120         * given_name: Alice
121         * email: alice@wonderland.net
122         * </pre>
123         *
124         * <p>Resulting key / value pair:
125         *
126         * <ul>
127         *     <li>Key: cae7t
128         *     <li>Value: Java POJO with fields {@code uid=cae7t},
129         *         {@code givenName=Alice}, {@code surname=Adams} and
130         *         {@code email=alice@wonderland.net}.
131         *     <li>Metadata: Default metadata (no expiration, etc).
132         * </ul>
133         *
134         * @param sqlRecord The SQL record. Must not be {@code null}.
135         *
136         * @return The Infinispan entry (key / value pair with optional
137         *         metadata).
138         */
139        InfinispanEntry<K,V> toInfinispanEntry(final Record sqlRecord);
140}