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