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 at 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         * <p>Infinispan entry:
085         *
086         * <ul>
087         *     <li>Key: cae7t
088         *     <li>Value: Java POJO with fields {@code uid=cae7t},
089         *         {@code givenName=Alice}, {@code surname=Adams} and
090         *         {@code email=alice@wonderland.net}.
091         *     <li>Metadata: Specifies the entry expiration and other
092         *         properties.
093         * </ul>
094         *
095         * <p>Resulting SQL record:
096         *
097         * <pre>
098         * uid: cae7t (key)
099         * surname: Adams
100         * given_name: Alice
101         * email: alice@wonderland.net
102         * </pre>
103         *
104         * @param infinispanEntry The Infinispan entry. Not {@code null}.
105         *
106         * @return The SQL record.
107         */
108        SQLRecord toSQLRecord(final InfinispanEntry<K,V> infinispanEntry);
109
110
111        /**
112         * Transforms the specified SQL record to an Infinispan entry (key /
113         * value / metadata triple).
114         *
115         * <p>Example:
116         *
117         * <p>SQL record:
118         *
119         * <pre>
120         * uid: cae7t
121         * surname: Adams
122         * given_name: Alice
123         * email: alice@wonderland.net
124         * </pre>
125         *
126         * <p>Resulting Infinispan entry:
127         *
128         * <ul>
129         *     <li>Key: cae7t
130         *     <li>Value: Java POJO with fields {@code uid=cae7t},
131         *         {@code givenName=Alice}, {@code surname=Adams} and
132         *         {@code email=alice@wonderland.net}.
133         *     <li>Metadata: Default metadata (no expiration, etc).
134         * </ul>
135         *
136         * @param sqlRecord The SQL record. Must not be {@code null}.
137         *
138         * @return The Infinispan entry (key / value pair with optional
139         *         metadata).
140         */
141        InfinispanEntry<K,V> toInfinispanEntry(final Record sqlRecord);
142}