[jbosscache-commits] JBoss Cache SVN: r6875 - in core/branches/flat/src/main/java/org/jboss/starobrno: loader and 1 other directory.
jbosscache-commits at lists.jboss.org
jbosscache-commits at lists.jboss.org
Wed Oct 8 10:34:05 EDT 2008
Author: jason.greene at jboss.com
Date: 2008-10-08 10:34:05 -0400 (Wed, 08 Oct 2008)
New Revision: 6875
Added:
core/branches/flat/src/main/java/org/jboss/starobrno/CacheSPI.java
core/branches/flat/src/main/java/org/jboss/starobrno/loader/
core/branches/flat/src/main/java/org/jboss/starobrno/loader/CacheLoader.java
Log:
Initial work on cache loader
Added: core/branches/flat/src/main/java/org/jboss/starobrno/CacheSPI.java
===================================================================
--- core/branches/flat/src/main/java/org/jboss/starobrno/CacheSPI.java (rev 0)
+++ core/branches/flat/src/main/java/org/jboss/starobrno/CacheSPI.java 2008-10-08 14:34:05 UTC (rev 6875)
@@ -0,0 +1,239 @@
+/*
+ * JBoss, Home of Professional Open Source.
+ * Copyright 2000 - 2008, Red Hat Middleware LLC, and individual contributors
+ * as indicated by the @author tags. See the copyright.txt file in the
+ * distribution for a full listing of individual contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+package org.jboss.starobrno;
+
+import net.jcip.annotations.ThreadSafe;
+import org.jboss.cache.buddyreplication.BuddyManager;
+import org.jboss.cache.buddyreplication.GravitateResult;
+import org.jboss.cache.factories.ComponentRegistry;
+import org.jboss.cache.interceptors.base.CommandInterceptor;
+import org.jboss.cache.loader.CacheLoader;
+import org.jboss.cache.loader.CacheLoaderManager;
+import org.jboss.cache.marshall.Marshaller;
+import org.jboss.cache.notifications.Notifier;
+import org.jboss.cache.statetransfer.StateTransferManager;
+import org.jboss.cache.transaction.GlobalTransaction;
+import org.jboss.cache.transaction.TransactionTable;
+import org.jboss.starobrno.context.InvocationContext;
+
+import javax.transaction.Transaction;
+import javax.transaction.TransactionManager;
+import java.util.List;
+import java.util.Set;
+
+/**
+ * A more detailed interface to {@link Cache}, which is used when writing plugins for or extending JBoss Cache. A reference
+ * to this interface should only be obtained when it is passed in to your code, for example when you write an
+ * {@link org.jboss.cache.interceptors.base.CommandInterceptor} or {@link CacheLoader}.
+ * <p/>
+ * <B><I>You should NEVER attempt to directly cast a {@link Cache} instance to this interface. In future, the implementation may not allow it.</I></B>
+ * <p/>
+ * This interface contains overridden method signatures of some methods from {@link Cache}, overridden to ensure return
+ * types of {@link Node} are replaced with {@link NodeSPI}.
+ * <p/>
+ *
+ * @author <a href="mailto:manik at jboss.org">Manik Surtani (manik at jboss.org)</a>
+ * @see NodeSPI
+ * @see Cache
+ * @see org.jboss.cache.loader.CacheLoader
+ * @since 2.0.0
+ */
+ at ThreadSafe
+public interface CacheSPI<K, V> extends Cache<K, V>
+{
+ /**
+ * Retrieves a reference to a running {@link javax.transaction.TransactionManager}, if one is configured.
+ * <p/>
+ * From 2.1.0, Interceptor authors should obtain this by injection rather than this method. See the
+ * {@link org.jboss.cache.factories.annotations.Inject} annotation.
+ *
+ * @return a TransactionManager
+ */
+ TransactionManager getTransactionManager();
+
+ /**
+ * Retrieves the current Interceptor chain.
+ * <p/>
+ * From 2.1.0, Interceptor authors should obtain this by injection rather than this method. See the
+ * {@link org.jboss.cache.factories.annotations.Inject} annotation.
+ *
+ * @return an immutable {@link List} of {@link org.jboss.cache.interceptors.base.CommandInterceptor}s configured for this cache, or
+ * <code>null</code> if {@link Cache#create() create()} has not been invoked
+ * and the interceptors thus do not exist.
+ */
+ List<CommandInterceptor> getInterceptorChain();
+
+ /**
+ * Retrieves an instance of a {@link Marshaller}, which is capable of
+ * converting Java objects to bytestreams and back in an efficient manner, which is
+ * also interoperable with bytestreams produced/consumed by other versions of JBoss
+ * Cache.
+ * <p/>
+ * The use of this marshaller is the <b>recommended</b> way of creating efficient,
+ * compatible, byte streams from objects.
+ * <p/>
+ * From 2.1.0, Interceptor authors should obtain this by injection rather than this method. See the
+ * {@link org.jboss.cache.factories.annotations.Inject} annotation.
+ *
+ * @return an instance of {@link Marshaller}
+ */
+ Marshaller getMarshaller();
+
+ /**
+ * Adds a custom interceptor to the interceptor chain, at specified position, where the first interceptor in the chain
+ * is at position 0 and the last one at getInterceptorChain().size() - 1.
+ *
+ * @param i the interceptor to add
+ * @param position the position to add the interceptor
+ */
+ void addInterceptor(CommandInterceptor i, int position);
+
+ /**
+ * Adds a custom interceptor to the interceptor chain, after an instance of the specified interceptor type. Throws a
+ * cache exception if it cannot find an interceptor of the specified type.
+ *
+ * @param i interceptor to add
+ * @param afterInterceptor interceptor type after which to place custom interceptor
+ */
+ void addInterceptor(CommandInterceptor i, Class<? extends CommandInterceptor> afterInterceptor);
+
+ /**
+ * Removes the interceptor at a specified position, where the first interceptor in the chain
+ * is at position 0 and the last one at getInterceptorChain().size() - 1.
+ *
+ * @param position the position at which to remove an interceptor
+ */
+ void removeInterceptor(int position);
+
+ /**
+ * Removes the interceptor of specified type.
+ *
+ * @param interceptorType type of interceptor to remove
+ */
+ void removeInterceptor(Class<? extends CommandInterceptor> interceptorType);
+
+ /**
+ * Retrieves the current CacheCacheLoaderManager instance associated with the current Cache instance.
+ * <p/>
+ * From 2.1.0, Interceptor authors should obtain this by injection rather than this method. See the
+ * {@link org.jboss.cache.factories.annotations.Inject} annotation.
+ *
+ * @return Retrieves a reference to the currently configured {@link org.jboss.cache.loader.CacheLoaderManager} if one or more cache loaders are configured, null otherwise.
+ */
+ CacheLoaderManager getCacheLoaderManager();
+
+ /**
+ * Retrieves the current BuddyManager instance associated with the current Cache instance.
+ * <p/>
+ * From 2.1.0, Interceptor authors should obtain this by injection rather than this method. See the
+ * {@link org.jboss.cache.factories.annotations.Inject} annotation.
+ *
+ * @return an instance of {@link BuddyManager} if buddy replication is enabled, null otherwise.
+ */
+ BuddyManager getBuddyManager();
+
+ /**
+ * Retrieves the current TransactionTable instance associated with the current Cache instance.
+ * <p/>
+ * From 2.1.0, Interceptor authors should obtain this by injection rather than this method. See the
+ * {@link org.jboss.cache.factories.annotations.Inject} annotation.
+ *
+ * @return the current {@link TransactionTable}
+ */
+ TransactionTable getTransactionTable();
+
+ /**
+ * Gets a handle of the RPC manager.
+ * <p/>
+ * From 2.1.0, Interceptor authors should obtain this by injection rather than this method. See the
+ * {@link org.jboss.cache.factories.annotations.Inject} annotation.
+ *
+ * @return the {@link org.jboss.cache.RPCManager} configured.
+ */
+ Object getRPCManager();
+
+ /**
+ * Retrieves the current StateTransferManager instance associated with the current Cache instance.
+ * <p/>
+ * From 2.1.0, Interceptor authors should obtain this by injection rather than this method. See the
+ * {@link org.jboss.cache.factories.annotations.Inject} annotation.
+ *
+ * @return the current {@link org.jboss.cache.statetransfer.StateTransferManager}
+ */
+ StateTransferManager getStateTransferManager();
+
+ /**
+ * Retrieves the current Notifier instance associated with the current Cache instance.
+ * <p/>
+ * From 2.1.0, Interceptor authors should obtain this by injection rather than this method. See the
+ * {@link org.jboss.cache.factories.annotations.Inject} annotation.
+ *
+ * @return the notifier attached with this instance of the cache. See {@link org.jboss.cache.notifications.Notifier}, a class
+ * that is responsible for emitting notifications to registered CacheListeners.
+ */
+ Notifier getNotifier();
+
+ /**
+ * @return the name of the cluster. Null if running in local mode.
+ */
+ String getClusterName();
+
+ /**
+ * Returns the global transaction for this local transaction.
+ * Optionally creates a new global transaction if it does not exist.
+ *
+ * @param tx the current transaction
+ * @param createIfNotExists if true creates a new transaction if none exists
+ * @return a GlobalTransaction
+ */
+ GlobalTransaction getCurrentTransaction(Transaction tx, boolean createIfNotExists);
+
+ /**
+ * Returns the transaction associated with the current thread.
+ * If a local transaction exists, but doesn't yet have a mapping to a
+ * GlobalTransaction, a new GlobalTransaction will be created and mapped to
+ * the local transaction. Note that if a local transaction exists, but is
+ * not ACTIVE or PREPARING, null is returned.
+ *
+ * @return A GlobalTransaction, or null if no (local) transaction was associated with the current thread
+ */
+ GlobalTransaction getCurrentTransaction();
+
+ /**
+ * Used with buddy replication's data gravitation interceptor. If marshalling is necessary, ensure that the cache is
+ * configured to use {@link org.jboss.cache.config.Configuration#useRegionBasedMarshalling} and the {@link org.jboss.cache.Region}
+ * pertaining to the Fqn passed in is activated, and has an appropriate ClassLoader.
+ *
+ * @param fqn the fqn to gravitate
+ * @param searchBuddyBackupSubtrees if true, buddy backup subtrees are searched and if false, they are not.
+ * @param ctx
+ * @return a GravitateResult which contains the data for the gravitation
+ */
+ GravitateResult gravitateData(K key, boolean searchBuddyBackupSubtrees, InvocationContext ctx);
+
+ /**
+ * Returns the component registry associated with this cache instance.
+ *
+ * @see org.jboss.cache.factories.ComponentRegistry
+ */
+ ComponentRegistry getComponentRegistry();
+}
Added: core/branches/flat/src/main/java/org/jboss/starobrno/loader/CacheLoader.java
===================================================================
--- core/branches/flat/src/main/java/org/jboss/starobrno/loader/CacheLoader.java (rev 0)
+++ core/branches/flat/src/main/java/org/jboss/starobrno/loader/CacheLoader.java 2008-10-08 14:34:05 UTC (rev 6875)
@@ -0,0 +1,241 @@
+/*
+ * JBoss, Home of Professional Open Source.
+ * Copyright 2000 - 2008, Red Hat Middleware LLC, and individual contributors
+ * as indicated by the @author tags. See the copyright.txt file in the
+ * distribution for a full listing of individual contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+package org.jboss.starobrno.loader;
+
+import java.io.ObjectInputStream;
+import java.io.ObjectOutputStream;
+import java.util.List;
+import java.util.Map;
+
+import net.jcip.annotations.ThreadSafe;
+
+import org.jboss.cache.CacheSPI;
+import org.jboss.cache.Fqn;
+import org.jboss.cache.Modification;
+import org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig;
+import org.jboss.cache.loader.AbstractCacheLoader;
+
+/**
+ * A {@link org.jboss.cache.loader.CacheLoader} implementation persists and load keys to and from
+ * secondary storage, such as a database or filesystem. Typically,
+ * implementations store a series of keys and values (an entire {@link Map})
+ * under a single {@link Fqn}. Loading and saving properties of an entire
+ * {@link Map} should be atomic.
+ * <p/>
+ * Lifecycle: First an instance of the loader is created, then the
+ * configuration ({@link #setConfig(org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig)}) and cache ({@link
+ * #setCache(CacheSPI)}) are set. After this, {@link #create()} is called.
+ * Then {@link #start()} is called. When re-deployed, {@link #stop()} will be
+ * called, followed by another {@link #start()}. Finally, when shut down,
+ * {@link #destroy()} is called, after which the loader is unusable.
+ * <p/>
+ * An {@link org.jboss.cache.loader.AbstractCacheLoader} is provided as a convenient starting place
+ * when implementing your own {@link org.jboss.cache.loader.CacheLoader}.
+ * <p/>
+ * It is important to note that all implementations are thread safe, as concurrent reads and writes, potentially even to
+ * the same {@link Fqn}, are possible.
+ * <p/>
+ *
+ * @author <a href="mailto:manik at jboss.org">Manik Surtani (manik at jboss.org)</a>
+ * @see CacheSPI
+ * @see org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig
+ * @see org.jboss.cache.loader.AbstractCacheLoader
+ * @since 2.0.0
+ */
+ at ThreadSafe
+public interface CacheLoader<K, V>
+{
+ /**
+ * Sets the configuration. This is called before {@link #create()} and {@link #start()}.
+ *
+ * @param config May be an instance of the {@link org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig} base
+ * class, in which case the cache loader should use the
+ * {@link org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig#getProperties()}
+ * method to find configuration information. Alternatively,
+ * may be a type-specific subclass of {@link org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig},
+ * if there is one.
+ */
+ void setConfig(IndividualCacheLoaderConfig config);
+
+ /**
+ * Gets the configuration.
+ *
+ * @return the configuration, represented by a {@link org.jboss.cache.config.CacheLoaderConfig.IndividualCacheLoaderConfig} object.
+ */
+ IndividualCacheLoaderConfig getConfig();
+
+ /**
+ * Sets the {@link CacheSPI} that is maintaining this CacheLoader.
+ * This method allows this CacheLoader to set a reference to the {@link CacheSPI}.
+ * This method is called be called after the CacheLoader instance has been constructed.
+ *
+ * @param c The cache on which this loader works
+ */
+ void setCache(CacheSPI<K,V> c);
+
+ /**
+ * Returns all keys and values from the persistent store, given a {@link org.jboss.cache.Fqn}
+ *
+ * @param name the {@link Fqn} to search for.
+ * @return Map<Object,Object> keys and values for the given node. Returns
+ * null if the node is not found. If the node is found but has no
+ * attributes, this method returns an empty Map.
+ */
+ V get(Object key) throws Exception;
+
+
+ /**
+ * Returns true if the CacheLoader has a node with a {@link Fqn}.
+ *
+ * @return true if node exists, false otherwise
+ */
+ boolean exists(Object key) throws Exception;
+
+ /**
+ * Puts a key and value into the attribute map of a given node. If the
+ * node does not exist, all parent nodes from the root down are created
+ * automatically. Returns the old value.
+ */
+ V put(Object key, V value) throws Exception;
+
+ /**
+ * Removes the given key and value from the attributes of the given node.
+ * Does nothing if the node doesn't exist
+ * Returns the removed value.
+ */
+ V remove(Object key, V value) throws Exception;
+
+ /**
+ * Removes the given node and all its subnodes, does nothing if the node does not exist.
+ *
+ * @param fqn the {@link Fqn} of the node
+ */
+ void remove(Object key) throws Exception;
+
+
+ /**
+ * Prepares a list of modifications. For example, for a DB-based CacheLoader:
+ * <ol>
+ * <li>Create a local (JDBC) transaction
+ * <li>Associate the local transaction with <code>tx</code> (tx is the key)
+ * <li>Execute the corresponding SQL statements against the DB (statements derived from modifications)
+ * </ol>
+ * For non-transactional CacheLoader (e.g. file-based), the implementation could attempt to implement its own transactional
+ * logic, attempting to write data to a temp location (or memory) and writing it to the proper location upon commit.
+ *
+ * @param tx The transaction, indended to be used by implementations as an identifier of the transaction (and not necessarily a JTA {@link javax.transaction.Transaction} object)
+ * @param modifications A {@link List} containing {@link org.jboss.cache.Modification}s, for the given transaction
+ * @param one_phase Persist immediately and (for example) commit the local JDBC transaction as well. When true,
+ * we won't get a {@link #commit(Object)} or {@link #rollback(Object)} method call later
+ * @throws Exception
+ */
+ void prepare(Object tx, List<Modification> modifications, boolean one_phase) throws Exception;
+
+ /**
+ * Commits the transaction. A DB-based CacheLoader would look up the local
+ * JDBC transaction asociated with <code>tx</code> and commit that
+ * transaction. Non-transactional CacheLoaders could simply write the data
+ * that was previously saved transiently under the given <code>tx</code>
+ * key, to (for example) a file system.
+ * <p/>
+ * <b>Note</b> this only holds if the previous prepare() did not define <pre>one_phase=true</pre>
+ *
+ * @param tx transaction to commit
+ */
+ void commit(Object tx) throws Exception;
+
+ /**
+ * Rolls the transaction back. A DB-based CacheLoader would look up the
+ * local JDBC transaction asociated with <code>tx</code> and roll back that
+ * transaction.
+ *
+ * @param tx transaction to roll back
+ */
+ void rollback(Object tx);
+
+ /**
+ * Fetches the entire state for this cache from secondary storage (disk, database)
+ * and writes it to a provided ObjectOutputStream. State written to the provided
+ * ObjectOutputStream parameter is used for initialization of a new CacheImpl instance.
+ * When the state gets transferred to the new cache instance its cacheloader calls
+ * {@link #storeEntireState(ObjectInputStream)}
+ * <p/>
+ * Implementations of this method should not catch any exception or close the
+ * given ObjectOutputStream parameter. In order to ensure cacheloader interoperability
+ * contents of the cache are written to the ObjectOutputStream as a sequence of
+ * NodeData objects.
+ * <p/>
+ * Default implementation is provided by {@link AbstractCacheLoader} and ensures cacheloader
+ * interoperability. Implementors are encouraged to consider extending AbstractCacheLoader
+ * prior to implementing completely custom cacheloader.
+ *
+ * @param os ObjectOutputStream to write state
+ * @see AbstractCacheLoader#loadEntireState(ObjectOutputStream)
+ * @see org.jboss.cache.marshall.NodeData
+ */
+ void loadEntireState(ObjectOutputStream os) throws Exception;
+
+ /**
+ * Stores the entire state for this cache by reading it from a provided ObjectInputStream.
+ * The state was provided to this cache by calling {@link #loadEntireState(ObjectOutputStream)}}
+ * on some other cache instance. State currently in storage gets overwritten.
+ * <p/>
+ * Implementations of this method should not catch any exception or close the
+ * given ObjectInputStream parameter. In order to ensure cacheloader interoperability
+ * contents of the cache are read from the ObjectInputStream as a sequence of
+ * NodeData objects.
+ * <p/>
+ * Default implementation is provided by {@link AbstractCacheLoader} and ensures cacheloader
+ * interoperability. Implementors are encouraged to consider extending AbstractCacheLoader
+ * prior to implementing completely custom cacheloader.
+ *
+ * @param is ObjectInputStream to read state
+ * @see AbstractCacheLoader#storeEntireState(ObjectInputStream)
+ * @see org.jboss.cache.marshall.NodeData
+ */
+ void storeEntireState(ObjectInputStream is) throws Exception;
+
+ /**
+ * Lifecycle method, called when the cache loader is created.
+ *
+ * @throws java.lang.Exception
+ */
+ void create() throws java.lang.Exception;
+
+ /**
+ * Lifecycle method, called when the cache loader is started.
+ *
+ * @throws java.lang.Exception
+ */
+ void start() throws java.lang.Exception;
+
+ /**
+ * Lifecycle method, called when the cache loader is stopped.
+ */
+ void stop();
+
+ /**
+ * Lifecycle method, called when the cache loader is destroyed.
+ */
+ void destroy();
+
+}
Property changes on: core/branches/flat/src/main/java/org/jboss/starobrno/loader/CacheLoader.java
___________________________________________________________________
Name: svn:executable
+ *
More information about the jbosscache-commits
mailing list