http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/8bf39571/geode-core/src/main/java/org/apache/geode/cache/CacheFactory.java ---------------------------------------------------------------------- diff --git a/geode-core/src/main/java/org/apache/geode/cache/CacheFactory.java b/geode-core/src/main/java/org/apache/geode/cache/CacheFactory.java index 6d3fd4b..b62feac 100644 --- a/geode-core/src/main/java/org/apache/geode/cache/CacheFactory.java +++ b/geode-core/src/main/java/org/apache/geode/cache/CacheFactory.java @@ -1,18 +1,16 @@ /* - * 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 + * 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 + * 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. + * 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. */ package org.apache.geode.cache; @@ -33,28 +31,38 @@ import org.apache.geode.pdx.PdxSerializer; /** - * Factory class used to create the singleton {@link Cache cache} and connect to the GemFire singleton {@link DistributedSystem distributed system}. If the application wants to connect to GemFire as a client it should use {@link org.apache.geode.cache.client.ClientCacheFactory} instead. -<p> Once the factory has been configured using its {@link #set(String, String)} method you produce a {@link Cache} by calling the {@link #create()} method. + * Factory class used to create the singleton {@link Cache cache} and connect to the GemFire + * singleton {@link DistributedSystem distributed system}. If the application wants to connect to + * GemFire as a client it should use {@link org.apache.geode.cache.client.ClientCacheFactory} + * instead. + * <p> + * Once the factory has been configured using its {@link #set(String, String)} method you produce a + * {@link Cache} by calling the {@link #create()} method. * <p> * To get the existing unclosed singleton cache instance call {@link #getAnyInstance}. * <p> - * If an instance of {@link DistributedSystem} already exists when this factory - * creates a cache, that instance will be used if it is compatible with this factory. -<p> -The following examples illustrate bootstrapping the cache using region shortcuts: -<p> -Example 1: Create a cache and a replicate region named customers. -<PRE> - Cache c = new CacheFactory().create(); - Region r = c.createRegionFactory(REPLICATE).create("customers"); -</PRE> -Example 2: Create a cache and a partition region with redundancy -<PRE> - Cache c = new CacheFactory().create(); - Region r = c.createRegionFactory(PARTITION_REDUNDANT).create("customers"); -</PRE> -Example 3: Construct the cache region declaratively in cache.xml -<PRE> + * If an instance of {@link DistributedSystem} already exists when this factory creates a cache, + * that instance will be used if it is compatible with this factory. + * <p> + * The following examples illustrate bootstrapping the cache using region shortcuts: + * <p> + * Example 1: Create a cache and a replicate region named customers. + * + * <PRE> + * Cache c = new CacheFactory().create(); + * Region r = c.createRegionFactory(REPLICATE).create("customers"); + * </PRE> + * + * Example 2: Create a cache and a partition region with redundancy + * + * <PRE> + * Cache c = new CacheFactory().create(); + * Region r = c.createRegionFactory(PARTITION_REDUNDANT).create("customers"); + * </PRE> + * + * Example 3: Construct the cache region declaratively in cache.xml + * + * <PRE> <!DOCTYPE cache PUBLIC "-//GemStone Systems, Inc.//GemFire Declarative Caching 8.0//EN" "http://www.gemstone.com/dtd/cache8_0.dtd"> @@ -63,17 +71,19 @@ Example 3: Construct the cache region declaratively in cache.xml <!-- you can override or add to the REPLICATE attributes by adding a region-attributes sub element here --> </cache> -</PRE> -Now, create the cache telling it to read your cache.xml file: -<PRE> - Cache c = new CacheFactory() - .set("cache-xml-file", "myCache.xml") - .create(); - Region r = c.getRegion("myRegion"); -</PRE> - -<p> For a complete list of all region shortcuts see {@link RegionShortcut}. -Applications that need to explicitly control the individual region attributes can do this declaratively in XML or using APIs. + * </PRE> + * + * Now, create the cache telling it to read your cache.xml file: + * + * <PRE> + * Cache c = new CacheFactory().set("cache-xml-file", "myCache.xml").create(); + * Region r = c.getRegion("myRegion"); + * </PRE> + * + * <p> + * For a complete list of all region shortcuts see {@link RegionShortcut}. Applications that need to + * explicitly control the individual region attributes can do this declaratively in XML or using + * APIs. * * * @@ -82,20 +92,22 @@ Applications that need to explicitly control the individual region attributes ca public class CacheFactory { private final Properties dsProps; - - private final CacheConfig cacheConfig = new CacheConfig(); - + + private final CacheConfig cacheConfig = new CacheConfig(); + /** * Creates a default cache factory. + * * @since GemFire 6.5 */ public CacheFactory() { this(null); } + /** - * Create a CacheFactory initialized with the given gemfire properties. - * For a list of valid GemFire properties and their meanings - * see {@linkplain ConfigurationProperties}. + * Create a CacheFactory initialized with the given gemfire properties. For a list of valid + * GemFire properties and their meanings see {@linkplain ConfigurationProperties}. + * * @param props the gemfire properties to initialize the factory with. * @since GemFire 6.5 */ @@ -107,9 +119,9 @@ public class CacheFactory { } /** - * Sets a gemfire property that will be used when creating the Cache. - * For a list of valid GemFire properties and their meanings - * see {@link ConfigurationProperties}. + * Sets a gemfire property that will be used when creating the Cache. For a list of valid GemFire + * properties and their meanings see {@link ConfigurationProperties}. + * * @param name the name of the gemfire property * @param value the value of the gemfire property * @return a reference to this CacheFactory object @@ -119,107 +131,80 @@ public class CacheFactory { this.dsProps.setProperty(name, value); return this; } + /** * Creates a new cache that uses the specified <code>system</code>. * * <p> * - * The <code>system</code> can specify a <A - * href="../distributed/DistributedSystem.html#cache-xml-file">"cache-xml-file"</a> - * property which will cause this creation to also create the - * regions, objects, and attributes declared in the file. The - * contents of the file must comply with the - * <code>"doc-files/cache8_0.dtd"></code> file. - * Note that when parsing the XML file {@link Declarable} classes - * are loaded using the current thread's {@linkplain - * Thread#getContextClassLoader context class loader}. + * The <code>system</code> can specify a + * <A href="../distributed/DistributedSystem.html#cache-xml-file">"cache-xml-file"</a> property + * which will cause this creation to also create the regions, objects, and attributes declared in + * the file. The contents of the file must comply with the <code>"doc-files/cache8_0.dtd"></code> + * file. Note that when parsing the XML file {@link Declarable} classes are loaded using the + * current thread's {@linkplain Thread#getContextClassLoader context class loader}. * - * @param system - * a <code>DistributedSystem</code> obtained by calling + * @param system a <code>DistributedSystem</code> obtained by calling * {@link DistributedSystem#connect}. * - * @return a <code>Cache</code> that uses the specified - * <code>system</code> for distribution. + * @return a <code>Cache</code> that uses the specified <code>system</code> for distribution. * - * @throws IllegalArgumentException - * If <code>system</code> is not {@link - * DistributedSystem#isConnected connected}. - * @throws CacheExistsException - * If an open cache already exists. - * @throws CacheXmlException - * If a problem occurs while parsing the declarative caching - * XML file. - * @throws TimeoutException - * If a {@link Region#put(Object, Object)} times out while initializing the - * cache. - * @throws CacheWriterException - * If a <code>CacheWriterException</code> is thrown while + * @throws IllegalArgumentException If <code>system</code> is not + * {@link DistributedSystem#isConnected connected}. + * @throws CacheExistsException If an open cache already exists. + * @throws CacheXmlException If a problem occurs while parsing the declarative caching XML file. + * @throws TimeoutException If a {@link Region#put(Object, Object)} times out while initializing + * the cache. + * @throws CacheWriterException If a <code>CacheWriterException</code> is thrown while * initializing the cache. - * @throws GatewayException - * If a <code>GatewayException</code> is thrown while - * initializing the cache. - * @throws RegionExistsException - * If the declarative caching XML file describes a region - * that already exists (including the root region). + * @throws GatewayException If a <code>GatewayException</code> is thrown while initializing the + * cache. + * @throws RegionExistsException If the declarative caching XML file describes a region that + * already exists (including the root region). * @deprecated as of 6.5 use {@link #CacheFactory(Properties)} instead. */ @Deprecated - public static synchronized Cache create(DistributedSystem system) - throws CacheExistsException, TimeoutException, CacheWriterException, - GatewayException, - RegionExistsException - { + public static synchronized Cache create(DistributedSystem system) throws CacheExistsException, + TimeoutException, CacheWriterException, GatewayException, RegionExistsException { return create(system, false, new CacheConfig()); } - - private static synchronized Cache create(DistributedSystem system, boolean existingOk, CacheConfig cacheConfig) - throws CacheExistsException, TimeoutException, CacheWriterException, - GatewayException, - RegionExistsException - { + + private static synchronized Cache create(DistributedSystem system, boolean existingOk, + CacheConfig cacheConfig) throws CacheExistsException, TimeoutException, CacheWriterException, + GatewayException, RegionExistsException { // Moved code in this method to GemFireCacheImpl.create return GemFireCacheImpl.create(system, existingOk, cacheConfig); } /** - * Creates a new cache that uses the configured distributed system. - * If a connected distributed system already exists it will be used - * if it is compatible with the properties on this factory. - * Otherwise a a distributed system will be created with the configured properties. - * If a cache already exists it will be returned. - * <p>If the cache does need to be created it will also be initialized from - * cache.xml if it exists. + * Creates a new cache that uses the configured distributed system. If a connected distributed + * system already exists it will be used if it is compatible with the properties on this factory. + * Otherwise a a distributed system will be created with the configured properties. If a cache + * already exists it will be returned. + * <p> + * If the cache does need to be created it will also be initialized from cache.xml if it exists. * * @return the created or already existing singleton cache * - * @throws CacheXmlException - * If a problem occurs while parsing the declarative caching - * XML file. - * @throws TimeoutException - * If a {@link Region#put(Object, Object)} times out while initializing the - * cache. - * @throws CacheWriterException - * If a <code>CacheWriterException</code> is thrown while + * @throws CacheXmlException If a problem occurs while parsing the declarative caching XML file. + * @throws TimeoutException If a {@link Region#put(Object, Object)} times out while initializing + * the cache. + * @throws CacheWriterException If a <code>CacheWriterException</code> is thrown while * initializing the cache. - * @throws GatewayException - * If a <code>GatewayException</code> is thrown while - * initializing the cache. - * @throws RegionExistsException - * If the declarative caching XML file describes a region - * that already exists (including the root region). - * @throws IllegalStateException if cache already exists and is not compatible - * with the new configuration. + * @throws GatewayException If a <code>GatewayException</code> is thrown while initializing the + * cache. + * @throws RegionExistsException If the declarative caching XML file describes a region that + * already exists (including the root region). + * @throws IllegalStateException if cache already exists and is not compatible with the new + * configuration. * @throws AuthenticationFailedException if authentication fails. - * @throws AuthenticationRequiredException if the distributed system is in secure mode - * and this new member is not configured with security credentials. + * @throws AuthenticationRequiredException if the distributed system is in secure mode and this + * new member is not configured with security credentials. * @since GemFire 6.5 */ public Cache create() - throws TimeoutException, CacheWriterException, - GatewayException, - RegionExistsException - { - synchronized(CacheFactory.class) { + throws TimeoutException, CacheWriterException, GatewayException, RegionExistsException { + synchronized (CacheFactory.class) { DistributedSystem ds = null; if (this.dsProps.isEmpty()) { // any ds will do @@ -233,20 +218,21 @@ public class CacheFactory { } /** - * Gets the instance of {@link Cache} produced by an - * earlier call to {@link #create()}. + * Gets the instance of {@link Cache} produced by an earlier call to {@link #create()}. + * * @param system the <code>DistributedSystem</code> the cache was created with. * @return the {@link Cache} associated with the specified system. - * @throws CacheClosedException if a cache has not been created - * or the created one is {@link Cache#isClosed closed} + * @throws CacheClosedException if a cache has not been created or the created one is + * {@link Cache#isClosed closed} */ public static Cache getInstance(DistributedSystem system) { return basicGetInstance(system, false); } /** - * Gets the instance of {@link Cache} produced by an - * earlier call to {@link #create()} even if it has been closed. + * Gets the instance of {@link Cache} produced by an earlier call to {@link #create()} even if it + * has been closed. + * * @param system the <code>DistributedSystem</code> the cache was created with. * @return the {@link Cache} associated with the specified system. * @throws CacheClosedException if a cache has not been created @@ -261,8 +247,8 @@ public class CacheFactory { // Avoid synchronization if this is an initialization thread to avoid // deadlock when messaging returns to this VM final int initReq = LocalRegion.threadInitLevelRequirement(); - if (initReq == LocalRegion.ANY_INIT - || initReq == LocalRegion.BEFORE_INITIAL_IMAGE) { // fix bug 33471 + if (initReq == LocalRegion.ANY_INIT || initReq == LocalRegion.BEFORE_INITIAL_IMAGE) { // fix bug + // 33471 return basicGetInstancePart2(system, closeOk); } else { synchronized (CacheFactory.class) { @@ -270,70 +256,80 @@ public class CacheFactory { } } } + private static Cache basicGetInstancePart2(DistributedSystem system, boolean closeOk) { GemFireCacheImpl instance = GemFireCacheImpl.getInstance(); if (instance == null) { - throw new CacheClosedException(LocalizedStrings.CacheFactory_A_CACHE_HAS_NOT_YET_BEEN_CREATED.toLocalizedString()); + throw new CacheClosedException( + LocalizedStrings.CacheFactory_A_CACHE_HAS_NOT_YET_BEEN_CREATED.toLocalizedString()); } else { if (instance.isClosed() && !closeOk) { - throw instance.getCacheClosedException(LocalizedStrings.CacheFactory_THE_CACHE_HAS_BEEN_CLOSED.toLocalizedString(), null); + throw instance.getCacheClosedException( + LocalizedStrings.CacheFactory_THE_CACHE_HAS_BEEN_CLOSED.toLocalizedString(), null); } if (!instance.getDistributedSystem().equals(system)) { - throw new CacheClosedException(LocalizedStrings.CacheFactory_A_CACHE_HAS_NOT_YET_BEEN_CREATED_FOR_THE_GIVEN_DISTRIBUTED_SYSTEM.toLocalizedString()); + throw new CacheClosedException( + LocalizedStrings.CacheFactory_A_CACHE_HAS_NOT_YET_BEEN_CREATED_FOR_THE_GIVEN_DISTRIBUTED_SYSTEM + .toLocalizedString()); } return instance; } } /** - * Gets an arbitrary open instance of {@link Cache} produced by an - * earlier call to {@link #create()}. - * @throws CacheClosedException if a cache has not been created - * or the only created one is {@link Cache#isClosed closed} + * Gets an arbitrary open instance of {@link Cache} produced by an earlier call to + * {@link #create()}. + * + * @throws CacheClosedException if a cache has not been created or the only created one is + * {@link Cache#isClosed closed} */ public static synchronized Cache getAnyInstance() { GemFireCacheImpl instance = GemFireCacheImpl.getInstance(); if (instance == null) { - throw new CacheClosedException(LocalizedStrings.CacheFactory_A_CACHE_HAS_NOT_YET_BEEN_CREATED.toLocalizedString()); + throw new CacheClosedException( + LocalizedStrings.CacheFactory_A_CACHE_HAS_NOT_YET_BEEN_CREATED.toLocalizedString()); } else { instance.getCancelCriterion().checkCancelInProgress(null); return instance; } } - /** Returns the version of the cache implementation. + /** + * Returns the version of the cache implementation. + * * @return the version of the cache implementation as a <code>String</code> */ public static String getVersion() { return GemFireVersion.getGemFireVersion(); } - - /** Sets the object preference to PdxInstance type. - * When a cached object that was serialized as a PDX is read - * from the cache a {@link PdxInstance} will be returned instead of the actual domain class. - * The PdxInstance is an interface that provides run time access to - * the fields of a PDX without deserializing the entire PDX. - * The PdxInstance implementation is a light weight wrapper - * that simply refers to the raw bytes of the PDX that are kept - * in the cache. Using this method applications can choose to - * access PdxInstance instead of Java object. - * <p>Note that a PdxInstance is only returned if a serialized PDX is found in the cache. - * If the cache contains a deserialized PDX, then a domain class instance is returned instead of a PdxInstance. - * - * @param readSerialized true to prefer PdxInstance - * @return this CacheFactory - * @since GemFire 6.6 - * @see org.apache.geode.pdx.PdxInstance + + /** + * Sets the object preference to PdxInstance type. When a cached object that was serialized as a + * PDX is read from the cache a {@link PdxInstance} will be returned instead of the actual domain + * class. The PdxInstance is an interface that provides run time access to the fields of a PDX + * without deserializing the entire PDX. The PdxInstance implementation is a light weight wrapper + * that simply refers to the raw bytes of the PDX that are kept in the cache. Using this method + * applications can choose to access PdxInstance instead of Java object. + * <p> + * Note that a PdxInstance is only returned if a serialized PDX is found in the cache. If the + * cache contains a deserialized PDX, then a domain class instance is returned instead of a + * PdxInstance. + * + * @param readSerialized true to prefer PdxInstance + * @return this CacheFactory + * @since GemFire 6.6 + * @see org.apache.geode.pdx.PdxInstance */ - public CacheFactory setPdxReadSerialized(boolean readSerialized) { + public CacheFactory setPdxReadSerialized(boolean readSerialized) { this.cacheConfig.setPdxReadSerialized(readSerialized); return this; } - + /** - * Set the PDX serializer for the cache. If this serializer is set, - * it will be consulted to see if it can serialize any domain classes which are - * added to the cache in portable data exchange format. + * Set the PDX serializer for the cache. If this serializer is set, it will be consulted to see if + * it can serialize any domain classes which are added to the cache in portable data exchange + * format. + * * @param serializer the serializer to use * @return this CacheFactory * @since GemFire 6.6 @@ -343,16 +339,15 @@ public class CacheFactory { this.cacheConfig.setPdxSerializer(serializer); return this; } - + /** - * Set the disk store that is used for PDX meta data. When - * serializing objects in the PDX format, the type definitions - * are persisted to disk. This setting controls which disk store - * is used for that persistence. + * Set the disk store that is used for PDX meta data. When serializing objects in the PDX format, + * the type definitions are persisted to disk. This setting controls which disk store is used for + * that persistence. * * If not set, the metadata will go in the default disk store. - * @param diskStoreName the name of the disk store to use - * for the PDX metadata. + * + * @param diskStoreName the name of the disk store to use for the PDX metadata. * @return this CacheFactory * @since GemFire 6.6 */ @@ -362,14 +357,12 @@ public class CacheFactory { } /** - * Control whether the type metadata for PDX objects is persisted to disk. The - * default for this setting is false. If you are using persistent regions with - * PDX then you must set this to true. If you are using a - * <code>GatewaySender</code> or <code>AsyncEventQueue</code> with PDX then - * you should set this to true. + * Control whether the type metadata for PDX objects is persisted to disk. The default for this + * setting is false. If you are using persistent regions with PDX then you must set this to true. + * If you are using a <code>GatewaySender</code> or <code>AsyncEventQueue</code> with PDX then you + * should set this to true. * - * @param isPersistent - * true if the metadata should be persistent + * @param isPersistent true if the metadata should be persistent * @return this CacheFactory * @since GemFire 6.6 */ @@ -377,17 +370,18 @@ public class CacheFactory { this.cacheConfig.setPdxPersistent(isPersistent); return this; } + /** - * Control whether pdx ignores fields that were unread during deserialization. - * The default is to preserve unread fields be including their data during serialization. - * But if you configure the cache to ignore unread fields then their data will be lost - * during serialization. - * <P>You should only set this attribute to <code>true</code> if you know this member - * will only be reading cache data. In this use case you do not need to pay the cost - * of preserving the unread fields since you will never be reserializing pdx data. + * Control whether pdx ignores fields that were unread during deserialization. The default is to + * preserve unread fields be including their data during serialization. But if you configure the + * cache to ignore unread fields then their data will be lost during serialization. + * <P> + * You should only set this attribute to <code>true</code> if you know this member will only be + * reading cache data. In this use case you do not need to pay the cost of preserving the unread + * fields since you will never be reserializing pdx data. * - * @param ignore <code>true</code> if fields not read during pdx deserialization should be ignored; - * <code>false</code>, the default, if they should be preserved. + * @param ignore <code>true</code> if fields not read during pdx deserialization should be + * ignored; <code>false</code>, the default, if they should be preserved. * @return this CacheFactory * @since GemFire 6.6 */ @@ -395,5 +389,5 @@ public class CacheFactory { this.cacheConfig.setPdxIgnoreUnreadFields(ignore); return this; } -} +}
http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/8bf39571/geode-core/src/main/java/org/apache/geode/cache/CacheListener.java ---------------------------------------------------------------------- diff --git a/geode-core/src/main/java/org/apache/geode/cache/CacheListener.java b/geode-core/src/main/java/org/apache/geode/cache/CacheListener.java index db4bb3c..8f23238 100644 --- a/geode-core/src/main/java/org/apache/geode/cache/CacheListener.java +++ b/geode-core/src/main/java/org/apache/geode/cache/CacheListener.java @@ -1,18 +1,16 @@ /* - * 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 + * 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 + * 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. + * 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. */ package org.apache.geode.cache; @@ -28,35 +26,30 @@ package org.apache.geode.cache; * * <h4>Avoiding the risk of deadlock</h4> * <p> - * The methods on a <code>CacheListener</code> are invoked while holding a lock - * on the entry described by the {@link EntryEvent}, as a result if the listener - * method takes a long time to execute then it will cause the operation that - * caused it to be invoked to take a long time. In addition, listener code which - * calls {@link Region} methods could result in a deadlock. For example, in - * {@link #afterUpdate(EntryEvent)} for entry key k1, - * {@link Region#put(Object, Object) put(k2, someVal)} is called at the same - * time {@link #afterUpdate(EntryEvent)} for entry key k2 calls - * {@link Region#put(Object, Object) put(k1, someVal)} a deadlock may result. - * This co-key dependency example can be extended to a co-Region dependency - * where listener code in Region "A" performs Region operations on "B" and - * listener code in Region "B" performs Region operations on "A". Deadlocks may - * be either java-level or distributed multi-VM dead locks depending on Region - * configuration. To be assured of no deadlocks, listener code should cause some - * other thread to access the region and must not wait for that thread to - * complete the task. + * The methods on a <code>CacheListener</code> are invoked while holding a lock on the entry + * described by the {@link EntryEvent}, as a result if the listener method takes a long time to + * execute then it will cause the operation that caused it to be invoked to take a long time. In + * addition, listener code which calls {@link Region} methods could result in a deadlock. For + * example, in {@link #afterUpdate(EntryEvent)} for entry key k1, {@link Region#put(Object, Object) + * put(k2, someVal)} is called at the same time {@link #afterUpdate(EntryEvent)} for entry key k2 + * calls {@link Region#put(Object, Object) put(k1, someVal)} a deadlock may result. This co-key + * dependency example can be extended to a co-Region dependency where listener code in Region "A" + * performs Region operations on "B" and listener code in Region "B" performs Region operations on + * "A". Deadlocks may be either java-level or distributed multi-VM dead locks depending on Region + * configuration. To be assured of no deadlocks, listener code should cause some other thread to + * access the region and must not wait for that thread to complete the task. * </p> * * <h4>Concurrency</h4> * <p> * Multiple events, on different entries, can cause concurrent invocation of - * <code>CacheListener</code> methods. Any exceptions thrown by the listener are - * caught by GemFire and logged. + * <code>CacheListener</code> methods. Any exceptions thrown by the listener are caught by GemFire + * and logged. * </p> * - * <h4>Declaring instances in Cache XML files</h4> + * <h4>Declaring instances in Cache XML files</h4> * <p> - * To declare a CacheListener in a Cache XML file, it must also implement - * {@link Declarable} + * To declare a CacheListener in a Cache XML file, it must also implement {@link Declarable} * </p> * * @@ -68,29 +61,27 @@ package org.apache.geode.cache; * @see AttributesMutator#initCacheListeners * @since GemFire 3.0 */ -public interface CacheListener<K,V> extends CacheCallback { +public interface CacheListener<K, V> extends CacheCallback { /** - * Handles the event of new key being added to a region. The entry did not - * previously exist in this region in the local cache (even with a null - * value). + * Handles the event of new key being added to a region. The entry did not previously exist in + * this region in the local cache (even with a null value). * * @param event the EntryEvent * @see Region#create(Object, Object) * @see Region#put(Object, Object) * @see Region#get(Object) */ - public void afterCreate(EntryEvent<K,V> event); + public void afterCreate(EntryEvent<K, V> event); /** - * Handles the event of an entry's value being modified in a region. This - * entry previously existed in this region in the local cache, but its - * previous value may have been null. + * Handles the event of an entry's value being modified in a region. This entry previously existed + * in this region in the local cache, but its previous value may have been null. * * @param event the EntryEvent * @see Region#put(Object, Object) */ - public void afterUpdate(EntryEvent<K,V> event); + public void afterUpdate(EntryEvent<K, V> event); /** * Handles the event of an entry's value being invalidated. @@ -98,7 +89,7 @@ public interface CacheListener<K,V> extends CacheCallback { * @param event the EntryEvent * @see Region#invalidate(Object) */ - public void afterInvalidate(EntryEvent<K,V> event); + public void afterInvalidate(EntryEvent<K, V> event); /** * Handles the event of an entry being destroyed. @@ -106,25 +97,23 @@ public interface CacheListener<K,V> extends CacheCallback { * @param event the EntryEvent * @see Region#destroy(Object) */ - public void afterDestroy(EntryEvent<K,V> event); + public void afterDestroy(EntryEvent<K, V> event); /** - * Handles the event of a region being invalidated. Events are not invoked for - * each individual value that is invalidated as a result of the region being - * invalidated. Each subregion, however, gets its own - * <code>regionInvalidated</code> event invoked on its listener. + * Handles the event of a region being invalidated. Events are not invoked for each individual + * value that is invalidated as a result of the region being invalidated. Each subregion, however, + * gets its own <code>regionInvalidated</code> event invoked on its listener. * * @param event the RegionEvent * @see Region#invalidateRegion() * @see Region#localInvalidateRegion() */ - public void afterRegionInvalidate(RegionEvent<K,V> event); + public void afterRegionInvalidate(RegionEvent<K, V> event); /** - * Handles the event of a region being destroyed. Events are not invoked for - * each individual entry that is destroyed as a result of the region being - * destroyed. Each subregion, however, gets its own - * <code>afterRegionDestroyed</code> event invoked on its listener. + * Handles the event of a region being destroyed. Events are not invoked for each individual entry + * that is destroyed as a result of the region being destroyed. Each subregion, however, gets its + * own <code>afterRegionDestroyed</code> event invoked on its listener. * * @param event the RegionEvent * @see Region#destroyRegion() @@ -132,26 +121,25 @@ public interface CacheListener<K,V> extends CacheCallback { * @see Region#close * @see Cache#close() */ - public void afterRegionDestroy(RegionEvent<K,V> event); + public void afterRegionDestroy(RegionEvent<K, V> event); /** - * Handles the event of a region being cleared. Events are not invoked for - * each individual entry that is removed as a result of the region being - * cleared. + * Handles the event of a region being cleared. Events are not invoked for each individual entry + * that is removed as a result of the region being cleared. * * @param event the RegionEvent * * @see Region#clear * @since GemFire 5.0 */ - public void afterRegionClear(RegionEvent<K,V> event); - + public void afterRegionClear(RegionEvent<K, V> event); + /** - * Handles the event of a region being created. Events are invoked for - * each individual region that is created. - * <p>Note that this method is only called - * for creates done in the local vm. To be notified of creates done in remote - * vms use {@link RegionMembershipListener#afterRemoteRegionCreate}. + * Handles the event of a region being created. Events are invoked for each individual region that + * is created. + * <p> + * Note that this method is only called for creates done in the local vm. To be notified of + * creates done in remote vms use {@link RegionMembershipListener#afterRemoteRegionCreate}. * * @param event the RegionEvent * @@ -159,7 +147,7 @@ public interface CacheListener<K,V> extends CacheCallback { * @see Region#createSubregion * @since GemFire 5.0 */ - public void afterRegionCreate(RegionEvent<K,V> event); + public void afterRegionCreate(RegionEvent<K, V> event); /** * Handles the event of a region being live after receiving the marker from the server. @@ -169,5 +157,5 @@ public interface CacheListener<K,V> extends CacheCallback { * @see Cache#readyForEvents * @since GemFire 5.5 */ - public void afterRegionLive(RegionEvent<K,V> event); + public void afterRegionLive(RegionEvent<K, V> event); } http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/8bf39571/geode-core/src/main/java/org/apache/geode/cache/CacheLoader.java ---------------------------------------------------------------------- diff --git a/geode-core/src/main/java/org/apache/geode/cache/CacheLoader.java b/geode-core/src/main/java/org/apache/geode/cache/CacheLoader.java index 7bb30c7..8812816 100644 --- a/geode-core/src/main/java/org/apache/geode/cache/CacheLoader.java +++ b/geode-core/src/main/java/org/apache/geode/cache/CacheLoader.java @@ -1,32 +1,28 @@ /* - * 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 + * 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 + * 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. + * 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. */ package org.apache.geode.cache; /** - * Allows data from outside of the VM to be placed into a region. - * When {@link org.apache.geode.cache.Region#get(Object)} is called for a region - * entry that has a <code>null</code> value, the - * {@link CacheLoader#load load} method of the - * region's cache loader is invoked. The <code>load</code> method - * creates the value for the desired key by performing an operation such - * as a database query. The <code>load</code> may also perform a - * {@linkplain LoaderHelper#netSearch net search} - * that will look for the value in a cache instance hosted by - * another member of the distributed system.</p> + * Allows data from outside of the VM to be placed into a region. When + * {@link org.apache.geode.cache.Region#get(Object)} is called for a region entry that has a + * <code>null</code> value, the {@link CacheLoader#load load} method of the region's cache loader is + * invoked. The <code>load</code> method creates the value for the desired key by performing an + * operation such as a database query. The <code>load</code> may also perform a + * {@linkplain LoaderHelper#netSearch net search} that will look for the value in a cache instance + * hosted by another member of the distributed system. + * </p> * * * @@ -35,29 +31,25 @@ package org.apache.geode.cache; * @see AttributesMutator#setCacheLoader * @since GemFire 2.0 */ -public interface CacheLoader<K,V> extends CacheCallback { +public interface CacheLoader<K, V> extends CacheCallback { /** - * Loads a value. Application writers should implement this - * method to customize the loading of a value. This method is called - * by the caching service when the requested value is not in the cache. - * Any exception (including an unchecked exception) thrown by this - * method is propagated back to and thrown by the invocation of - * {@link Region#get(Object, Object)} that triggered this load. + * Loads a value. Application writers should implement this method to customize the loading of a + * value. This method is called by the caching service when the requested value is not in the + * cache. Any exception (including an unchecked exception) thrown by this method is propagated + * back to and thrown by the invocation of {@link Region#get(Object, Object)} that triggered this + * load. * <p> * - * @param helper a LoaderHelper object that is passed in from cache service - * and provides access to the key, region, argument, and <code>netSearch</code>. - * @return the value supplied for this key, or null if no value can be - * supplied. A local loader will always be invoked if one exists. - * Otherwise one remote loader is invoked. - * Returning <code>null</code> causes - * {@link Region#get(Object, Object)} to return <code>null</code>. - * @throws CacheLoaderException, if an error occurs. This exception or any - * other exception thrown by this method will be propagated back to the - * application from the get method. + * @param helper a LoaderHelper object that is passed in from cache service and provides access to + * the key, region, argument, and <code>netSearch</code>. + * @return the value supplied for this key, or null if no value can be supplied. A local loader + * will always be invoked if one exists. Otherwise one remote loader is invoked. Returning + * <code>null</code> causes {@link Region#get(Object, Object)} to return + * <code>null</code>. + * @throws CacheLoaderException, if an error occurs. This exception or any other exception thrown + * by this method will be propagated back to the application from the get method. * - * @see Region#get(Object, Object) Region.get + * @see Region#get(Object, Object) Region.get */ - public V load(LoaderHelper<K,V> helper) - throws CacheLoaderException; + public V load(LoaderHelper<K, V> helper) throws CacheLoaderException; } http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/8bf39571/geode-core/src/main/java/org/apache/geode/cache/CacheLoaderException.java ---------------------------------------------------------------------- diff --git a/geode-core/src/main/java/org/apache/geode/cache/CacheLoaderException.java b/geode-core/src/main/java/org/apache/geode/cache/CacheLoaderException.java index 30e8ebe..65d147a 100755 --- a/geode-core/src/main/java/org/apache/geode/cache/CacheLoaderException.java +++ b/geode-core/src/main/java/org/apache/geode/cache/CacheLoaderException.java @@ -1,25 +1,24 @@ /* - * 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 + * 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 + * 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. + * 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. */ package org.apache.geode.cache; -/** Thrown from the {@link CacheLoader#load} method indicating that an error - * occurred when a CacheLoader was attempting to load a value. This - * exception is propagated back to the caller of <code>Region.get</code>. +/** + * Thrown from the {@link CacheLoader#load} method indicating that an error occurred when a + * CacheLoader was attempting to load a value. This exception is propagated back to the caller of + * <code>Region.get</code>. * * * @@ -28,35 +27,37 @@ package org.apache.geode.cache; * @since GemFire 3.0 */ public class CacheLoaderException extends OperationAbortedException { -private static final long serialVersionUID = -3383072059406642140L; - + private static final long serialVersionUID = -3383072059406642140L; + /** * Creates a new instance of <code>CacheLoaderException</code>. */ - public CacheLoaderException() { - } - - + public CacheLoaderException() {} + + /** * Constructs an instance of <code>CacheLoaderException</code> with the specified detail message. + * * @param msg the detail message */ public CacheLoaderException(String msg) { super(msg); } - + /** * Constructs an instance of <code>CacheLoaderException</code> with the specified detail message * and cause. + * * @param msg the detail message * @param cause the causal Throwable */ public CacheLoaderException(String msg, Throwable cause) { super(msg, cause); } - + /** * Constructs an instance of <code>CacheLoaderException</code> with the specified cause. + * * @param cause the causal Throwable */ public CacheLoaderException(Throwable cause) { http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/8bf39571/geode-core/src/main/java/org/apache/geode/cache/CacheRuntimeException.java ---------------------------------------------------------------------- diff --git a/geode-core/src/main/java/org/apache/geode/cache/CacheRuntimeException.java b/geode-core/src/main/java/org/apache/geode/cache/CacheRuntimeException.java index d103e6a..a723b32 100644 --- a/geode-core/src/main/java/org/apache/geode/cache/CacheRuntimeException.java +++ b/geode-core/src/main/java/org/apache/geode/cache/CacheRuntimeException.java @@ -1,27 +1,25 @@ /* - * 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 + * 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 + * 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. + * 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. */ package org.apache.geode.cache; import org.apache.geode.GemFireException; -/** A generic runtime exception that indicates - * a cache error has occurred. All the other runtime cache exceptions are the - * subclass of this class. This class is abstract so only subclasses can be +/** + * A generic runtime exception that indicates a cache error has occurred. All the other runtime + * cache exceptions are the subclass of this class. This class is abstract so only subclasses can be * instantiated * * @@ -33,30 +31,32 @@ public abstract class CacheRuntimeException extends GemFireException { /** * Creates a new instance of <code>CacheRuntimeException</code> without detail message. */ - public CacheRuntimeException() { - } - - + public CacheRuntimeException() {} + + /** * Constructs an instance of <code>CacheRuntimeException</code> with the specified detail message. + * * @param msg the detail message */ public CacheRuntimeException(String msg) { super(msg); } - + /** * Constructs an instance of <code>CacheRuntimeException</code> with the specified detail message * and cause. + * * @param msg the detail message * @param cause the causal Throwable */ public CacheRuntimeException(String msg, Throwable cause) { super(msg, cause); } - + /** * Constructs an instance of <code>CacheRuntimeException</code> with the specified cause. + * * @param cause the causal Throwable */ public CacheRuntimeException(Throwable cause) { @@ -71,9 +71,7 @@ public abstract class CacheRuntimeException extends GemFireException { String causeStr = cause.toString(); final String glue = ", caused by "; StringBuffer sb = new StringBuffer(result.length() + causeStr.length() + glue.length()); - sb.append(result) - .append(glue) - .append(causeStr); + sb.append(result).append(glue).append(causeStr); result = sb.toString(); } return result; http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/8bf39571/geode-core/src/main/java/org/apache/geode/cache/CacheStatistics.java ---------------------------------------------------------------------- diff --git a/geode-core/src/main/java/org/apache/geode/cache/CacheStatistics.java b/geode-core/src/main/java/org/apache/geode/cache/CacheStatistics.java index 5738c30..05839cc 100644 --- a/geode-core/src/main/java/org/apache/geode/cache/CacheStatistics.java +++ b/geode-core/src/main/java/org/apache/geode/cache/CacheStatistics.java @@ -1,26 +1,23 @@ /* - * 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 + * 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 + * 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. + * 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. */ package org.apache.geode.cache; /** - * Defines common statistics information - * for both region and entries. All of these methods may throw a - * CacheClosedException, RegionDestroyedException or an EntryDestroyedException. + * Defines common statistics information for both region and entries. All of these methods may throw + * a CacheClosedException, RegionDestroyedException or an EntryDestroyedException. * * * @@ -29,26 +26,23 @@ package org.apache.geode.cache; * @since GemFire 2.0 */ -public interface CacheStatistics -{ - /** For an entry, returns the time that the entry's value was last modified; - * for a region, the last time any of the region's entries' values or the - * values in subregions' entries were modified. The - * modification may have been initiated locally or it may have been an update - * distributed from another cache. It may also have been a new value provided - * by a loader. The modification time on a region is propagated upward to parent - * regions, transitively, to the root region. +public interface CacheStatistics { + /** + * For an entry, returns the time that the entry's value was last modified; for a region, the last + * time any of the region's entries' values or the values in subregions' entries were modified. + * The modification may have been initiated locally or it may have been an update distributed from + * another cache. It may also have been a new value provided by a loader. The modification time on + * a region is propagated upward to parent regions, transitively, to the root region. * <p> - * The number is expressed as the number of milliseconds since January 1, 1970. - * The granularity may be as course as 100ms, so the accuracy may be off by - * up to 50ms. + * The number is expressed as the number of milliseconds since January 1, 1970. The granularity + * may be as course as 100ms, so the accuracy may be off by up to 50ms. * <p> - * Entry and subregion creation will update the modification time on a - * region, but <code>destroy</code>, <code>destroyRegion</code>, - * <code>invalidate</code>, and <code>invalidateRegion</code> - * do not update the modification time. - * @return the last modification time of the region or the entry; - * returns 0 if entry is invalid or modification time is uninitialized. + * Entry and subregion creation will update the modification time on a region, but + * <code>destroy</code>, <code>destroyRegion</code>, <code>invalidate</code>, and + * <code>invalidateRegion</code> do not update the modification time. + * + * @return the last modification time of the region or the entry; returns 0 if entry is invalid or + * modification time is uninitialized. * @see Region#put(Object, Object) * @see Region#get(Object) * @see Region#create(Object, Object) @@ -57,21 +51,18 @@ public interface CacheStatistics public long getLastModifiedTime(); /** - * For an entry, returns the last time it was accessed via <code>Region.get</code>; - * for a region, the last time any of its entries or the entries of its - * subregions were accessed with <code>Region.get</code>. - * Any modifications will also update the lastAccessedTime, so - * <code>lastAccessedTime</code> is always <code>>= lastModifiedTime</code>. - * The <code>lastAccessedTime</code> on a region is propagated upward to - * parent regions, transitively, to the the root region. + * For an entry, returns the last time it was accessed via <code>Region.get</code>; for a region, + * the last time any of its entries or the entries of its subregions were accessed with + * <code>Region.get</code>. Any modifications will also update the lastAccessedTime, so + * <code>lastAccessedTime</code> is always <code>>= lastModifiedTime</code>. The + * <code>lastAccessedTime</code> on a region is propagated upward to parent regions, transitively, + * to the the root region. * <p> - * The number is expressed as the number of milliseconds - * since January 1, 1970. - * The granularity may be as course as 100ms, so the accuracy may be off by - * up to 50ms. + * The number is expressed as the number of milliseconds since January 1, 1970. The granularity + * may be as course as 100ms, so the accuracy may be off by up to 50ms. * - * @return the last access time of the region or the entry's value; - * returns 0 if entry is invalid or access time is uninitialized. + * @return the last access time of the region or the entry's value; returns 0 if entry is invalid + * or access time is uninitialized. * @see Region#get(Object) * @see #getLastModifiedTime * @throws StatisticsDisabledException if statistics are not available @@ -79,49 +70,48 @@ public interface CacheStatistics public long getLastAccessedTime() throws StatisticsDisabledException; /** - * Returns the number of times that {@link Region#get(Object) Region.get} on - * the region or the entry was called and there was no value found - * locally. Unlike <code>lastAccessedTime</code>, the miss count is - * not propagated to parent regions. Note that remote operations - * such as a "net search" do not effect the miss count. + * Returns the number of times that {@link Region#get(Object) Region.get} on the region or the + * entry was called and there was no value found locally. Unlike <code>lastAccessedTime</code>, + * the miss count is not propagated to parent regions. Note that remote operations such as a "net + * search" do not effect the miss count. * - * @return the number of cache misses on the region or the - * entry. + * @return the number of cache misses on the region or the entry. * @throws StatisticsDisabledException if statistics are not available */ public long getMissCount() throws StatisticsDisabledException; - + /** - * Returns the number of hits for this region or entry. The number - * of hits is defined as the number of times when the - * {@link Region#get(Object) Region.get} finds a value locally. Unlike - * <code>lastAccessedTime</code>, the hit count is not propagated to - * parent regions. Note that remote operations such as a "net - * search" do not effect the hit count. + * Returns the number of hits for this region or entry. The number of hits is defined as the + * number of times when the {@link Region#get(Object) Region.get} finds a value locally. Unlike + * <code>lastAccessedTime</code>, the hit count is not propagated to parent regions. Note that + * remote operations such as a "net search" do not effect the hit count. * * @return the number of hits for this region or entry. * @throws StatisticsDisabledException if statistics are not available */ public long getHitCount() throws StatisticsDisabledException; - - /** Return the hit ratio, a convenience method defined as the ratio of hits - * to the number of calls to {@link Region#get(Object) Region.get}. If there have been zero - * calls to <code>Region.get</code>, then zero is returned. - * <p> - * The hit ratio is equivalent to: - * <pre> - * long hitCount = getHitCount(); - * long total = hitCount + getMissCount(); - * return total == 0L ? 0.0f : ((float)hitCount / total); - * </pre> + + /** + * Return the hit ratio, a convenience method defined as the ratio of hits to the number of calls + * to {@link Region#get(Object) Region.get}. If there have been zero calls to + * <code>Region.get</code>, then zero is returned. + * <p> + * The hit ratio is equivalent to: + * + * <pre> + * long hitCount = getHitCount(); + * long total = hitCount + getMissCount(); + * return total == 0L ? 0.0f : ((float) hitCount / total); + * </pre> * - * @throws StatisticsDisabledException if statistics are not available - * @return the hit ratio as a float + * @throws StatisticsDisabledException if statistics are not available + * @return the hit ratio as a float */ public float getHitRatio() throws StatisticsDisabledException; - - - /** Reset the missCount and hitCount to zero for this entry. + + + /** + * Reset the missCount and hitCount to zero for this entry. * * @throws StatisticsDisabledException if statistics are not available */ http://git-wip-us.apache.org/repos/asf/incubator-geode/blob/8bf39571/geode-core/src/main/java/org/apache/geode/cache/CacheTransactionManager.java ---------------------------------------------------------------------- diff --git a/geode-core/src/main/java/org/apache/geode/cache/CacheTransactionManager.java b/geode-core/src/main/java/org/apache/geode/cache/CacheTransactionManager.java index 90651f3..8d9c694 100644 --- a/geode-core/src/main/java/org/apache/geode/cache/CacheTransactionManager.java +++ b/geode-core/src/main/java/org/apache/geode/cache/CacheTransactionManager.java @@ -1,18 +1,16 @@ /* - * 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 + * 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 + * 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. + * 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. */ package org.apache.geode.cache; @@ -20,80 +18,85 @@ package org.apache.geode.cache; import java.util.concurrent.TimeUnit; -/** <p>The CacheTransactionManager interface allows applications to manage - * transactions on a per {@link Cache} basis. +/** + * <p> + * The CacheTransactionManager interface allows applications to manage transactions on a per + * {@link Cache} basis. * - * <p>The life cycle of a GemFire transaction starts with a begin - * operation. The life cycle ends with either a commit or rollback - * operation. Between the begin and the commit/rollback are typically - * {@link Region} operations. In general, those that either create, - * destroy, invalidate or update {@link Region.Entry} are considered - * transactional, that is they modify transactional state. + * <p> + * The life cycle of a GemFire transaction starts with a begin operation. The life cycle ends with + * either a commit or rollback operation. Between the begin and the commit/rollback are typically + * {@link Region} operations. In general, those that either create, destroy, invalidate or update + * {@link Region.Entry} are considered transactional, that is they modify transactional state. * - * <p>A GemFire transaction may involve operations on multiple regions, - * each of which may have different attributes. + * <p> + * A GemFire transaction may involve operations on multiple regions, each of which may have + * different attributes. * - * <p>While a GemFire transaction and its operations are invoked in - * the local VM, the resulting transaction state is distributed to - * other VM's at commit time as per the attributes of each + * <p> + * While a GemFire transaction and its operations are invoked in the local VM, the resulting + * transaction state is distributed to other VM's at commit time as per the attributes of each * participant Region. * - * <p>A transaction can have no more than one thread associated with - * it and conversely a thread can only operate on one transaction at - * any given time. Child threads will not inherit the existing + * <p> + * A transaction can have no more than one thread associated with it and conversely a thread can + * only operate on one transaction at any given time. Child threads will not inherit the existing * transaction. * - * <p>Each of the following methods operate on the current thread. All - * methods throw {@link CacheClosedException} if the Cache is closed. + * <p> + * Each of the following methods operate on the current thread. All methods throw + * {@link CacheClosedException} if the Cache is closed. * - * <p>GemFire Transactions currently only support Read Committed - * isolation. In addition, they are optimistic transactions in that - * write locking and conflict checks are performed as part of the + * <p> + * GemFire Transactions currently only support Read Committed isolation. In addition, they are + * optimistic transactions in that write locking and conflict checks are performed as part of the * commit operation. * - * <p>For guaranteed Read Committed isolation, avoid making "in place" - * changes, because such changes will be "seen" by other transactions - * and break the Read Committed isolation guarantee. e.g. + * <p> + * For guaranteed Read Committed isolation, avoid making "in place" changes, because such changes + * will be "seen" by other transactions and break the Read Committed isolation guarantee. e.g. * - * <pre> - * CacheTransactionManager txMgr = cache.getCacheTransactionManager(); - * txMgr.begin(); - * StringBuffer s = (StringBuffer) r.get("stringBuf"); - * s.append("Changes seen before commit. NOT Read Committed!"); - * r.put("stringBuf", s); - * txMgr.commit(); - * </pre> + * <pre> + * CacheTransactionManager txMgr = cache.getCacheTransactionManager(); + * txMgr.begin(); + * StringBuffer s = (StringBuffer) r.get("stringBuf"); + * s.append("Changes seen before commit. NOT Read Committed!"); + * r.put("stringBuf", s); + * txMgr.commit(); + * </pre> * - * <p>To aid in creating copies, the "copy on read" - * <code>Cache</code> attribute and the {@link - * org.apache.geode.CopyHelper#copy} method are provided. - * The following is a Read Committed safe example using the - * <code>CopyHelper.copy</code> method. + * <p> + * To aid in creating copies, the "copy on read" <code>Cache</code> attribute and the + * {@link org.apache.geode.CopyHelper#copy} method are provided. The following is a Read Committed + * safe example using the <code>CopyHelper.copy</code> method. * - * <pre> - * CacheTransactionManager txMgr = cache.getCacheTransactionManager(); - * txMgr.begin(); - * Object o = r.get("stringBuf"); - * StringBuffer s = (StringBuffer) CopyHelper.copy(o); - * s.append("Changes unseen before commit. Read Committed."); - * r.put("stringBuf", s); - * txMgr.commit(); - * </pre> + * <pre> + * CacheTransactionManager txMgr = cache.getCacheTransactionManager(); + * txMgr.begin(); + * Object o = r.get("stringBuf"); + * StringBuffer s = (StringBuffer) CopyHelper.copy(o); + * s.append("Changes unseen before commit. Read Committed."); + * r.put("stringBuf", s); + * txMgr.commit(); + * </pre> * - * <p>Its important to note that creating copies can negatively - * impact both performance and memory consumption. + * <p> + * Its important to note that creating copies can negatively impact both performance and memory + * consumption. * - * <p>Partitioned Regions, Distributed No Ack and Distributed Ack Regions are supported - * (see {@link AttributesFactory} for Scope). For both scopes, a - * consistent configuration (per VM) is enforced. + * <p> + * Partitioned Regions, Distributed No Ack and Distributed Ack Regions are supported (see + * {@link AttributesFactory} for Scope). For both scopes, a consistent configuration (per VM) is + * enforced. * - * <p>Global Regions, client Regions (see org.apache.geode.cache.client package) - * and persistent Regions (see {@link DiskWriteAttributes}) do not - * support transactions. + * <p> + * Global Regions, client Regions (see org.apache.geode.cache.client package) and persistent Regions + * (see {@link DiskWriteAttributes}) do not support transactions. * - * <p>When PartitionedRegions are involved in a transaction, all data in the - * transaction must be colocated together on one data node. See the GemFire - * Developer Guide for details on using transactions with Partitioned Regions. + * <p> + * When PartitionedRegions are involved in a transaction, all data in the transaction must be + * colocated together on one data node. See the GemFire Developer Guide for details on using + * transactions with Partitioned Regions. * * * @since GemFire 4.0 @@ -102,82 +105,75 @@ import java.util.concurrent.TimeUnit; * */ public interface CacheTransactionManager { - /** Creates a new transaction and associates it with the current thread. - * - * @throws IllegalStateException if the thread is already associated with a transaction - * - * @since GemFire 4.0 - */ - public void begin(); + /** + * Creates a new transaction and associates it with the current thread. + * + * @throws IllegalStateException if the thread is already associated with a transaction + * + * @since GemFire 4.0 + */ + public void begin(); - /** Commit the transaction associated with the current thread. If - * the commit operation fails due to a conflict it will destroy - * the transaction state and throw a {@link - * CommitConflictException}. If the commit operation succeeds, - * it returns after the transaction state has been merged with - * committed state. When this method completes, the thread is no - * longer associated with a transaction. - * - * @throws IllegalStateException if the thread is not associated with a transaction - * - * @throws CommitConflictException if the commit operation fails due to - * a write conflict. - * - * @throws TransactionDataNodeHasDepartedException if the node hosting the - * transaction data has departed. This is only relevant for transaction that - * involve PartitionedRegions. - * - * @throws TransactionDataNotColocatedException if at commit time, the data - * involved in the transaction has moved away from the transaction hosting - * node. This can only happen if rebalancing/recovery happens during a - * transaction that involves a PartitionedRegion. - * - * @throws TransactionInDoubtException when GemFire cannot tell which nodes - * have applied the transaction and which have not. This only occurs if nodes - * fail mid-commit, and only then in very rare circumstances. - */ - public void commit() throws CommitConflictException; + /** + * Commit the transaction associated with the current thread. If the commit operation fails due to + * a conflict it will destroy the transaction state and throw a {@link CommitConflictException}. + * If the commit operation succeeds, it returns after the transaction state has been merged with + * committed state. When this method completes, the thread is no longer associated with a + * transaction. + * + * @throws IllegalStateException if the thread is not associated with a transaction + * + * @throws CommitConflictException if the commit operation fails due to a write conflict. + * + * @throws TransactionDataNodeHasDepartedException if the node hosting the transaction data has + * departed. This is only relevant for transaction that involve PartitionedRegions. + * + * @throws TransactionDataNotColocatedException if at commit time, the data involved in the + * transaction has moved away from the transaction hosting node. This can only happen if + * rebalancing/recovery happens during a transaction that involves a PartitionedRegion. + * + * @throws TransactionInDoubtException when GemFire cannot tell which nodes have applied the + * transaction and which have not. This only occurs if nodes fail mid-commit, and only + * then in very rare circumstances. + */ + public void commit() throws CommitConflictException; - /** Roll back the transaction associated with the current thread. When - * this method completes, the thread is no longer associated with a - * transaction and the transaction context is destroyed. - * - * @since GemFire 4.0 - * - * @throws IllegalStateException if the thread is not associated with a transaction - */ - public void rollback(); + /** + * Roll back the transaction associated with the current thread. When this method completes, the + * thread is no longer associated with a transaction and the transaction context is destroyed. + * + * @since GemFire 4.0 + * + * @throws IllegalStateException if the thread is not associated with a transaction + */ + public void rollback(); /** - * Suspends the transaction on the current thread. All subsequent operations - * performed by this thread will be non-transactional. The suspended - * transaction can be resumed by calling {@link #resume(TransactionId)} + * Suspends the transaction on the current thread. All subsequent operations performed by this + * thread will be non-transactional. The suspended transaction can be resumed by calling + * {@link #resume(TransactionId)} * - * @return the transaction identifier of the suspended transaction or null if - * the thread was not associated with a transaction + * @return the transaction identifier of the suspended transaction or null if the thread was not + * associated with a transaction * @since GemFire 6.6.2 */ public TransactionId suspend(); /** - * On the current thread, resumes a transaction that was previously suspended - * using {@link #suspend()} + * On the current thread, resumes a transaction that was previously suspended using + * {@link #suspend()} * - * @param transactionId - * the transaction to resume - * @throws IllegalStateException - * if the thread is associated with a transaction or if - * {@link #isSuspended(TransactionId)} would return false for the - * given transactionId + * @param transactionId the transaction to resume + * @throws IllegalStateException if the thread is associated with a transaction or if + * {@link #isSuspended(TransactionId)} would return false for the given transactionId * @since GemFire 6.6.2 * @see #tryResume(TransactionId) */ public void resume(TransactionId transactionId); /** - * This method can be used to determine if a transaction with the given - * transaction identifier is currently suspended locally. This method does not - * check other members for transaction status. + * This method can be used to determine if a transaction with the given transaction identifier is + * currently suspended locally. This method does not check other members for transaction status. * * @param transactionId * @return true if the transaction is in suspended state, false otherwise @@ -187,28 +183,29 @@ public interface CacheTransactionManager { public boolean isSuspended(TransactionId transactionId); /** - * On the current thread, resumes a transaction that was previously suspended - * using {@link #suspend()}. + * On the current thread, resumes a transaction that was previously suspended using + * {@link #suspend()}. * * This method is equivalent to + * * <pre> * if (isSuspended(txId)) { * resume(txId); * } * </pre> + * * except that this action is performed atomically * - * @param transactionId - * the transaction to resume + * @param transactionId the transaction to resume * @return true if the transaction was resumed, false otherwise * @since GemFire 6.6.2 */ public boolean tryResume(TransactionId transactionId); /** - * On the current thread, resumes a transaction that was previously suspended - * using {@link #suspend()}, or waits for the specified timeout interval if - * the transaction has not been suspended. This method will return if: + * On the current thread, resumes a transaction that was previously suspended using + * {@link #suspend()}, or waits for the specified timeout interval if the transaction has not been + * suspended. This method will return if: * <ul> * <li>Another thread suspends the transaction</li> * <li>Another thread calls commit/rollback on the transaction</li> @@ -217,12 +214,9 @@ public interface CacheTransactionManager { * * This method returns immediately if {@link #exists(TransactionId)} returns false. * - * @param transactionId - * the transaction to resume - * @param time - * the maximum time to wait - * @param unit - * the time unit of the <code>time</code> argument + * @param transactionId the transaction to resume + * @param time the maximum time to wait + * @param unit the time unit of the <code>time</code> argument * @return true if the transaction was resumed, false otherwise * @since GemFire 6.6.2 * @see #tryResume(TransactionId) @@ -230,120 +224,129 @@ public interface CacheTransactionManager { public boolean tryResume(TransactionId transactionId, long time, TimeUnit unit); /** - * Reports the existence of a transaction for the given transactionId. This - * method can be used to determine if a transaction with the given transaction - * identifier is currently in progress locally. + * Reports the existence of a transaction for the given transactionId. This method can be used to + * determine if a transaction with the given transaction identifier is currently in progress + * locally. * - * @param transactionId - * the given transaction identifier + * @param transactionId the given transaction identifier * @return true if the transaction is in progress, false otherwise. * @since GemFire 6.6.2 * @see #isSuspended(TransactionId) */ public boolean exists(TransactionId transactionId); - - /** Reports the existence of a Transaction for this thread - * - * @return true if a transaction exists, false otherwise - * - * @since GemFire 4.0 - */ - public boolean exists(); - /** Returns the transaction identifier for the current thread - * - * @return the transaction identifier or null if no transaction exists - * - * @since GemFire 4.0 - */ - public TransactionId getTransactionId(); + /** + * Reports the existence of a Transaction for this thread + * + * @return true if a transaction exists, false otherwise + * + * @since GemFire 4.0 + */ + public boolean exists(); - /** - * Gets the transaction listener for this Cache. - * - * @return The TransactionListener instance or null if no listener. - * @throws IllegalStateException if more than one listener exists on this cache - * @deprecated as of GemFire 5.0, use {@link #getListeners} instead - */ - @Deprecated - public TransactionListener getListener(); + /** + * Returns the transaction identifier for the current thread + * + * @return the transaction identifier or null if no transaction exists + * + * @since GemFire 4.0 + */ + public TransactionId getTransactionId(); - /** Returns an array of all the transaction listeners on this cache. - * Modifications to the returned array will not effect what listeners are on this cache. - * @return the cache's <code>TransactionListener</code>s; an empty array if no listeners - * @since GemFire 5.0 - */ - public TransactionListener[] getListeners(); + /** + * Gets the transaction listener for this Cache. + * + * @return The TransactionListener instance or null if no listener. + * @throws IllegalStateException if more than one listener exists on this cache + * @deprecated as of GemFire 5.0, use {@link #getListeners} instead + */ + @Deprecated + public TransactionListener getListener(); - /** - * Sets the transaction listener for this Cache. - * - * @param newListener the TransactionListener to register with the Cache. - * Use a <code>null</code> to deregister the current listener without - * registering a new one. - * @return the previous TransactionListener - * @throws IllegalStateException if more than one listener exists on this cache - * @deprecated as of GemFire 5.0, use {@link #addListener} or {@link #initListeners} instead. - */ - @Deprecated - public TransactionListener setListener(TransactionListener newListener); - /** - * Adds a transaction listener to the end of the list of transaction listeners on this cache. - * @param aListener the user defined transaction listener to add to the cache. - * @throws IllegalArgumentException if <code>aListener</code> is null - * @since GemFire 5.0 - */ - public void addListener(TransactionListener aListener); - /** - * Removes a transaction listener from the list of transaction listeners on this cache. - * Does nothing if the specified listener has not been added. - * If the specified listener has been added then {@link CacheCallback#close} will - * be called on it; otherwise does nothing. - * @param aListener the transaction listener to remove from the cache. - * @throws IllegalArgumentException if <code>aListener</code> is null - * @since GemFire 5.0 - */ - public void removeListener(TransactionListener aListener); - /** - * Removes all transaction listeners, calling {@link CacheCallback#close} on each of them, and then adds each listener in the specified array. - * @param newListeners a possibly null or empty array of listeners to add to this cache. - * @throws IllegalArgumentException if the <code>newListeners</code> array has a null element - * @since GemFire 5.0 - */ - public void initListeners(TransactionListener[] newListeners); + /** + * Returns an array of all the transaction listeners on this cache. Modifications to the returned + * array will not effect what listeners are on this cache. + * + * @return the cache's <code>TransactionListener</code>s; an empty array if no listeners + * @since GemFire 5.0 + */ + public TransactionListener[] getListeners(); - /** - * Set the TransactionWriter for the cache - * @param writer - * @see TransactionWriter - * @since GemFire 6.5 - */ - public void setWriter(TransactionWriter writer); + /** + * Sets the transaction listener for this Cache. + * + * @param newListener the TransactionListener to register with the Cache. Use a <code>null</code> + * to deregister the current listener without registering a new one. + * @return the previous TransactionListener + * @throws IllegalStateException if more than one listener exists on this cache + * @deprecated as of GemFire 5.0, use {@link #addListener} or {@link #initListeners} instead. + */ + @Deprecated + public TransactionListener setListener(TransactionListener newListener); - /** - * Returns the current {@link TransactionWriter} - * @see CacheTransactionManager#setWriter(TransactionWriter) - * @return the current {@link TransactionWriter} - * @since GemFire 6.5 - */ - public TransactionWriter getWriter(); - - /** - * Sets whether transactions should be executed in distributed or - * non-distributed mode. Once set this mode should not be changed during - * the course of transactions. - * - * @throws IllegalStateException if a transaction is already in progress - * and this method sets the distributed mode to a different value. - * @since Geode 1.0 - */ - public void setDistributed(boolean distributed); - - /** - * Returns the execution mode of transactions - * @return true if distributed, - * false otherwise. - * @since Geode 1.0 - */ - public boolean isDistributed(); + /** + * Adds a transaction listener to the end of the list of transaction listeners on this cache. + * + * @param aListener the user defined transaction listener to add to the cache. + * @throws IllegalArgumentException if <code>aListener</code> is null + * @since GemFire 5.0 + */ + public void addListener(TransactionListener aListener); + + /** + * Removes a transaction listener from the list of transaction listeners on this cache. Does + * nothing if the specified listener has not been added. If the specified listener has been added + * then {@link CacheCallback#close} will be called on it; otherwise does nothing. + * + * @param aListener the transaction listener to remove from the cache. + * @throws IllegalArgumentException if <code>aListener</code> is null + * @since GemFire 5.0 + */ + public void removeListener(TransactionListener aListener); + + /** + * Removes all transaction listeners, calling {@link CacheCallback#close} on each of them, and + * then adds each listener in the specified array. + * + * @param newListeners a possibly null or empty array of listeners to add to this cache. + * @throws IllegalArgumentException if the <code>newListeners</code> array has a null element + * @since GemFire 5.0 + */ + public void initListeners(TransactionListener[] newListeners); + + /** + * Set the TransactionWriter for the cache + * + * @param writer + * @see TransactionWriter + * @since GemFire 6.5 + */ + public void setWriter(TransactionWriter writer); + + /** + * Returns the current {@link TransactionWriter} + * + * @see CacheTransactionManager#setWriter(TransactionWriter) + * @return the current {@link TransactionWriter} + * @since GemFire 6.5 + */ + public TransactionWriter getWriter(); + + /** + * Sets whether transactions should be executed in distributed or non-distributed mode. Once set + * this mode should not be changed during the course of transactions. + * + * @throws IllegalStateException if a transaction is already in progress and this method sets the + * distributed mode to a different value. + * @since Geode 1.0 + */ + public void setDistributed(boolean distributed); + + /** + * Returns the execution mode of transactions + * + * @return true if distributed, false otherwise. + * @since Geode 1.0 + */ + public boolean isDistributed(); }