[infinispan-commits] Infinispan SVN: r1151 - trunk/core/src/main/java/org/infinispan/config.
infinispan-commits at lists.jboss.org
infinispan-commits at lists.jboss.org
Thu Nov 12 08:56:35 EST 2009
Author: manik.surtani at jboss.com
Date: 2009-11-12 08:56:35 -0500 (Thu, 12 Nov 2009)
New Revision: 1151
Modified:
trunk/core/src/main/java/org/infinispan/config/CacheLoaderManagerConfig.java
trunk/core/src/main/java/org/infinispan/config/Configuration.java
trunk/core/src/main/java/org/infinispan/config/CustomInterceptorConfig.java
trunk/core/src/main/java/org/infinispan/config/GlobalConfiguration.java
trunk/core/src/main/java/org/infinispan/config/InfinispanConfiguration.java
Log:
Better config docs
Modified: trunk/core/src/main/java/org/infinispan/config/CacheLoaderManagerConfig.java
===================================================================
--- trunk/core/src/main/java/org/infinispan/config/CacheLoaderManagerConfig.java 2009-11-12 12:56:26 UTC (rev 1150)
+++ trunk/core/src/main/java/org/infinispan/config/CacheLoaderManagerConfig.java 2009-11-12 13:56:35 UTC (rev 1151)
@@ -43,7 +43,7 @@
* they provide meta data for configuration file XML schema generation. Please modify these
* annotations and Java element types they annotate with utmost understanding and care.
*
- * @configRef name="loaders",desc="Holds the configuration of the cache loader chain."
+ * @configRef name="loaders",desc="Holds the configuration for cache loaders and stores."
*
* @author <a href="mailto:manik at jboss.org">Manik Surtani (manik at jboss.org)</a>
* @author Brian Stansberry
@@ -58,10 +58,12 @@
/**
* @configRef desc="If true, data is only written to the cache store when it is evicted from memory,
- * a phenomenon known as passivation. Next time the data is requested, it will be activated which
- * means that data will be brought back to memory and deleted from the persistent store.
+ * a phenomenon known as 'passivation'. Next time the data is requested, it will be 'activated' which
+ * means that data will be brought back to memory and removed from the persistent store. This gives you
+ * the ability to 'overflow' to disk, similar to swapping in an operating system.
+ * <p />
* If false, the cache store contains a copy of the contents in memory, so writes to cache
- * result in cache store writes."
+ * result in cache store writes. This essentially gives you a 'write-through' configuration."
* */
protected Boolean passivation = false;
@@ -69,16 +71,20 @@
* @configRef desc= "If true, when the cache starts, data stored in the cache store will be pre-loaded into
* memory. This is particularly useful when data in the cache store will be needed immediately
* after startup and you want to avoid cache operations being delayed as a result of loading this
- * data."
+ * data lazily. Can be used to provide a 'warm-cache' on startup, however there is a performance
+ * penalty as startup time is affected by this process."
* */
protected Boolean preload = false;
/**
- * @configRef desc="This setting should be set to true when multiple cache instances share the same cache store
- * in order to avoid multiple cache writing the same cache modification multiple times. So if true,
- * only the node where the cache modification originated will write to the cache store. If false,
- * each individual cache reacts to a potential replication message by storing the data to the cache
- * store. Note that this could be useful if each individual cache has its own cache store.
+ * @configRef desc="This setting should be set to true when multiple cache instances share the same cache store
+ * (e.g., multiple nodes in a cluster using a JDBC-based CacheStore pointing to the same, shared
+ * database.) Setting this to true avoids multiple cache instances writing the same modification multiple
+ * times. If enabled, only the node where the modification originated will write to the cache store.
+ * <p />
+ * If disabled, each individual cache reacts to a potential remote update by storing the data to the cache
+ * store. Note that this could be useful if each individual node has its own cache store - perhaps local
+ * on-disk.
* */
protected Boolean shared = false;
Modified: trunk/core/src/main/java/org/infinispan/config/Configuration.java
===================================================================
--- trunk/core/src/main/java/org/infinispan/config/Configuration.java 2009-11-12 12:56:26 UTC (rev 1150)
+++ trunk/core/src/main/java/org/infinispan/config/Configuration.java 2009-11-12 13:56:35 UTC (rev 1151)
@@ -54,9 +54,12 @@
* provide meta data for configuration file XML schema generation. Please modify these annotations
* and Java element types they annotate with utmost understanding and care.
*
- * @configRef name="default",desc="Configures the default cache which can be retrieved via CacheManager.getCache()"
- * @configRef name="namedCache",desc="Configures a named cache whose name can be passed to CacheManager.getCache(String)
- * in order to retrieve the cache instance."
+ * @configRef name="default",desc="Configures the default cache which can be retrieved via CacheManager.getCache().
+ * These default settings are also used as a starting point when configuring namedCaches,
+ * since the default settings are inherited by any named cache."
+ * @configRef name="namedCache",desc="Configures a named cache whose name can be passed to CacheManager.getCache(String)
+ * in order to retrieve the named instance. Named caches inherit settings from the
+ * default, and additional behavior can be specified or overridden."
*
* @author <a href="mailto:manik at jboss.org">Manik Surtani (manik at jboss.org)</a>
* @author Vladimir Blagojevic
@@ -75,7 +78,7 @@
private GlobalConfiguration globalConfiguration;
/**
- * @configRef desc="Cache name if this is a namedCache"
+ * @configRef desc="Only used with the namedCache element, this attribute specifies the name of the cache. Can be any String, but must be unique in a given configuration."
* */
@XmlAttribute
protected String name;
@@ -718,7 +721,9 @@
private static final long serialVersionUID = -3867090839830874603L;
/**
- * @configRef desc="Fully qualified class name of a class that should look up a reference to {@link javax.transaction.TransactionManager}"
+ * @configRef desc="Fully qualified class name of a class that looks up a reference to a {@link javax.transaction.TransactionManager}.
+ * The default provided is capable of locating the default TransactionManager in most popular Java EE systems,
+ * using a JNDI lookup."
* */
protected String transactionManagerLookupClass;
@@ -726,26 +731,29 @@
protected TransactionManagerLookup transactionManagerLookup;
/**
- * @configRef desc="If true, commit phase in two-phase commit (2PC) transactions will be synchronous, so Infinispan
- * will wait for responses from all nodes to which the commit was sent. Otherwise, the commit phase will
- * be asynchronous. Keeping it as false improves performance of 2PC transactions."
+ * @configRef desc="If true, the cluster-wide commit phase in two-phase commit (2PC) transactions will be synchronous,
+ * so Infinispan will wait for responses from all nodes to which the commit was sent. Otherwise, the
+ * commit phase will be asynchronous. Keeping it as false improves performance of 2PC transactions, since
+ * any remote failures are trapped during the prepare phase anyway and appropriate rollbacks are issued."
* */
@Dynamic
protected Boolean syncCommitPhase = false;
/**
- * @configRef desc="If true, rollback phase in two-phase commit (2PC) transactions will be synchronous, so Infinispan
- * will wait for responses from all nodes to which the rollback was sent. Otherwise, the rollback phase will
- * be asynchronous. Keeping it as false improves performance of 2PC transactions."
- * */
+ * @configRef desc="If true, the cluster-wide rollback phase in two-phase commit (2PC) transactions will be synchronous,
+ * so Infinispan will wait for responses from all nodes to which the rollback was sent. Otherwise, the
+ * rollback phase will be asynchronous. Keeping it as false improves performance of 2PC transactions."
+ */
+
@Dynamic
protected Boolean syncRollbackPhase = false;
/**
- * @configRef desc="By eager locking is set to true, whenever a lock on key is required, this lock will be acquired
- * cluster-wide. If false, locks are only acquired during two-phase prepare/commit phase. Note that this setting
- * is implicit and so it's indiscriminate. Alternatively, you can keep this setting as false and instead do eager
- * locking explicitly on a per invocation basis calling AdvancedCache.lock(Object)".
+ * @configRef desc="When eager locking is set to true, whenever a lock on key is required, cluster-wide locks will
+ * be acquired at the same time as local, in-VM locks. If false, cluster-wide locks are only acquired
+ * during the prepare phase in the two-phase commit protocol. Note that this setting
+ * is implicit and so it's indiscriminate. Alternatively, you can keep this setting as false and instead
+ * do eager locking explicitly on a per invocation basis by calling AdvancedCache.lock(Object)".
* */
@Dynamic
protected Boolean useEagerLocking = false;
@@ -819,7 +827,7 @@
}
/**
*
- * @configRef name="locking",desc="Defines locking characteristics of the cache."
+ * @configRef name="locking",desc="Defines the local, in-VM locking and concurrency characteristics of the cache."
*/
@XmlAccessorType(XmlAccessType.PROPERTY)
public static class LockingType extends AbstractNamedCacheConfigurationBean{
@@ -827,27 +835,31 @@
/** The serialVersionUID */
private static final long serialVersionUID = 8142143187082119506L;
- /** @configRef desc="Maximum time to attempt particular lock acquisition" */
+ /** @configRef desc="Maximum time to attempt a particular lock acquisition" */
@Dynamic
protected Long lockAcquisitionTimeout = 10000L;
- /** @configRef desc="Cache isolation level. Infinispan only allows READ_COMMITTED
- * or REPEATABLE_READ isolation levels." */
+ /** @configRef desc="Cache isolation level. Infinispan only supports READ_COMMITTED
+ * or REPEATABLE_READ isolation levels. See <a href="http://en.wikipedia.org/wiki/Isolation_level">http://en.wikipedia.org/wiki/Isolation_level</a>
+ * for a discussion on isolation levels." */
protected IsolationLevel isolationLevel = IsolationLevel.READ_COMMITTED;
/** @configRef desc="This setting is only applicable in the case of REPEATABLE_READ.
- * When write skew check is set to true, if the writer at commit time discovers that the working
- * node and the underlying node have different versions, the working node will override the
- * underlying node. If false, such version conflict will throw an Exception. */
+ * When write skew check is set to false, if the writer at commit time discovers that the working
+ * entry and the underlying entry have different versions, the working entry will overwrite the
+ * underlying entry. If true, such version conflict - known as a write-skew - will throw an Exception. */
protected Boolean writeSkewCheck = false;
- /** @configRef desc="If true, a pool of shared locks is maintained for all the elements that need to be locked.
- * Otherwise, a lock is created per entry in the cache. */
+ /** @configRef desc="If true, a pool of shared locks is maintained for all entries that need to be locked.
+ * Otherwise, a lock is created per entry in the cache. Lock striping helps control memory footprint
+ * but may reduce concurrency in the system."
+ */
protected Boolean useLockStriping = true;
/** @configRef desc="Concurrency level for lock containers. Adjust this value according to the number of concurrent
- * threads interating with Infinispan"*/
- protected Integer concurrencyLevel = 500;
+ * threads interating with Infinispan. Similar to the concurrencyLevel tuning parameter seen in
+ * the JDK's ConcurrentHashMap."*/
+ protected Integer concurrencyLevel = 512;
@XmlAttribute
public void setLockAcquisitionTimeout(Long lockAcquisitionTimeout) {
@@ -916,7 +928,7 @@
}
/**
- * @configRef name="clustering",desc="Defines clustering characteristics of the cache."
+ * @configRef name="clustering",desc="Defines clustered characteristics of the cache."
*/
@XmlJavaTypeAdapter(ClusteringTypeAdapter.class)
@XmlAccessorType(XmlAccessType.PROPERTY)
@@ -927,9 +939,9 @@
private static final long serialVersionUID = 4048135465543498430L;
/**
- * @configRef name="mode",desc="Cache mode. For distribution, set mode to either 'd', 'dist' or distribution.
+ * @configRef name="mode",desc="Cache mode. For distribution, set mode to either 'd', 'dist' or 'distribution'.
* For replication, use either 'r', 'repl' or 'replication'. Finally, for invalidation,
- * 'i', 'inv' or 'invalidation'. */
+ * 'i', 'inv' or 'invalidation'.*/
@XmlAttribute(name="mode")
protected String stringMode;
@@ -1050,8 +1062,7 @@
* @configRef name="async",parentName="clustering",desc="If this element is present, all communications are
* asynchronous, in that whenever a thread sends a message sent over the wire, it does not wait
* for an acknowledgement before returning. This element is mutually exclusive with the <sync />
- * element."
- * Characteristics of this can be tuned here.
+ * element.<p />Characteristics of this can be tuned here."
*/
@XmlAccessorType(XmlAccessType.PROPERTY)
public static class AsyncType extends AbstractNamedCacheConfigurationBean {
@@ -1147,8 +1158,7 @@
}
/**
- *
- * @configRef name="expiration",desc="This element controls the expiration settings globally for this particular cache."
+ * @configRef name="expiration",desc="This element controls the default expiration settings for entries in the cache."
*/
@XmlAccessorType(XmlAccessType.PROPERTY)
public static class ExpirationType extends AbstractNamedCacheConfigurationBean{
@@ -1156,11 +1166,15 @@
/** The serialVersionUID */
private static final long serialVersionUID = 5757161438110848530L;
- /** @configRef desc="Maximum lifespan of a cache entry, after which the entry is expired cluster-wide."*/
+ /** @configRef desc="Maximum lifespan of a cache entry, after which the entry is expired cluster-wide. -1 means the entries never expire.
+ * <p />Note that this can be overriden on a per-entry bassi by using the Cache API."
+ */
protected Long lifespan=-1L;
/** @configRef desc="Maximum idle time a cache entry will be maintained in the cache. If the idle time
- * is exceeded, the entry will be expired cluster-wide." */
+ * is exceeded, the entry will be expired cluster-wide. -1 means the entries never expire.
+ * <p />Note that this can be overriden on a per-entry bassi by using the Cache API."
+ */
protected Long maxIdle=-1L;
@XmlAttribute
@@ -1201,7 +1215,7 @@
}
/**
- * @configRef name="eviction",desc="This element controls the eviction settings globally for this particular cache."
+ * @configRef name="eviction",desc="This element controls the eviction settings for the cache."
*/
@XmlAccessorType(XmlAccessType.PROPERTY)
public static class EvictionType extends AbstractNamedCacheConfigurationBean {
@@ -1209,14 +1223,15 @@
/** The serialVersionUID */
private static final long serialVersionUID = -1248563712058858791L;
- /** @configRef desc="Interval between subsequent eviction runs. If you wish to disable the eviction thread, set
- * wakeupInterval to -1."*/
+ /** @configRef desc="Interval between subsequent eviction runs. If you wish to disable the periodic eviction process
+ * altogether, set wakeupInterval to -1."
+ */
protected Long wakeUpInterval=5000L;
- /** @configRef desc="Eviction strategy. Available options are 'FIFO' and 'LRU'."*/
+ /** @configRef desc="Eviction strategy. Available options are 'NONE', 'FIFO' and 'LRU'."*/
protected EvictionStrategy strategy=EvictionStrategy.NONE;
- /** @configRef desc="Maximum number of entries in a cache instance." */
+ /** @configRef desc="Maximum number of entries in a cache instance. -1 means no limit." */
protected Integer maxEntries=-1;
@XmlAttribute
@@ -1266,7 +1281,8 @@
}
/**
- * @configRef name="stateRetrieval",desc="Configures how state is retrieved when a new cache joins the cluster."
+ * @configRef name="stateRetrieval",desc="Configures how state is retrieved when a new cache joins the cluster. This
+ * element is only used with invalidation and replication clustered modes."
*/
@XmlAccessorType(XmlAccessType.PROPERTY)
public static class StateRetrievalType extends AbstractNamedCacheConfigurationBean {
@@ -1275,7 +1291,7 @@
private static final long serialVersionUID = 3709234918426217096L;
/** @configRef desc="If true, this will cause the cache to ask neighboring caches for state when it starts up,
- * so the cache starts "warm". " */
+ * so the cache starts 'warm', although it will impact startup time." */
@Dynamic
protected Boolean fetchInMemoryState = false;
@@ -1290,7 +1306,7 @@
/** @configRef desc="Wait time increase factor over successive state retrieval backoffs"*/
protected Integer retryWaitTimeIncreaseFactor = 2;
- /** @configRef desc="Number of state retrieval retries"*/
+ /** @configRef desc="Number of state retrieval retries before giving up and aborting startup."*/
protected Integer numRetries = 5;
@XmlAttribute
@@ -1357,8 +1373,8 @@
/**
* @configRef name="sync",desc="If this element is present, all communications are synchronous, in that whenever a
* thread sends a message sent over the wire, it blocks until it receives an acknowledgement from the
- * recipient. This element is mutually exclusive with the <async /> element."
- * Characteristics of this can be tuned here.
+ * recipient. This element is mutually exclusive with the <async /> element. <p />Characteristics of this can be tuned here."
+ *
*/
@XmlAccessorType(XmlAccessType.PROPERTY)
public static class SyncType extends AbstractNamedCacheConfigurationBean {
@@ -1366,7 +1382,7 @@
private static final long serialVersionUID = 8419216253674289524L;
/** @configRef desc="This is the timeout used to wait for an acknowledgement when making a remote call, after
- * which an exception is thrown. "*/
+ * which the call is aborted and an exception is thrown. "*/
@Dynamic
protected Long replTimeout=15000L;
@@ -1489,7 +1505,7 @@
}
/**
- * @configRef name="l1",desc="This element configures the L1 cache behaivour in 'distributed' caches instances.
+ * @configRef name="l1",desc="This element configures the L1 cache behavior in 'distributed' caches instances.
* In any other cache modes, this element is ignored. "
*/
@XmlAccessorType(XmlAccessType.PROPERTY)
@@ -1501,7 +1517,7 @@
/** @configRef desc="Toggle to enable/disable L1 cache." */
protected Boolean enabled=true;
- /** @configRef desc="Maximum lifespan of an entry in the L1 cache." */
+ /** @configRef desc="Maximum lifespan of an entry placed in the L1 cache." */
protected Long lifespan=600000L;
/** @configRef desc="If true, entries removed due to a rehash will be moved to L1 rather than being removed
@@ -1634,7 +1650,7 @@
}
/**
- * @configRef name="invocationBatching",desc="Defines whether invocation batching is allowed in this cache instance."
+ * @configRef name="invocationBatching",desc="Defines whether invocation batching is allowed in this cache instance, and sets up internals accordingly to allow use of this API."
*/
public static class InvocationBatching extends BooleanAttributeType {
/** The serialVersionUID */
@@ -1798,7 +1814,7 @@
}
/**
- * @configRef name="indexing",desc="Configures query module."
+ * @configRef name="indexing",desc="Configures indexing of entries in the cache for searching."
*/
@XmlAccessorType(XmlAccessType.PROPERTY)
public static class QueryConfigurationBean extends AbstractConfigurationBean {
@@ -1806,10 +1822,10 @@
/** The serialVersionUID */
private static final long serialVersionUID = 2891683014353342549L;
- /** @configRef desc="enabled TODO" */
+ /** @configRef desc="If enabled, entries will be indexed when they are added to the cache. INdexes will be updated as entries change or are removed." */
protected Boolean enabled = false;
- /** @configRef desc="indexLocalOnly TODO" */
+ /** @configRef desc="If true, only index changes made locally, ignoring remote changes. This is useful if indexes are shared across a cluster." */
protected Boolean indexLocalOnly = false;
public Boolean isEnabled() {
Modified: trunk/core/src/main/java/org/infinispan/config/CustomInterceptorConfig.java
===================================================================
--- trunk/core/src/main/java/org/infinispan/config/CustomInterceptorConfig.java 2009-11-12 12:56:26 UTC (rev 1150)
+++ trunk/core/src/main/java/org/infinispan/config/CustomInterceptorConfig.java 2009-11-12 13:56:35 UTC (rev 1151)
@@ -42,8 +42,8 @@
* provide meta data for configuration file XML schema generation. Please modify these annotations
* and Java element types they annotate with utmost understanding and care.
*
- * @configRef name="interceptor",desc=" This element allows you configure a custom interceptor. This tag may appear
- * multiple times."
+ * @configRef name="interceptor",desc=" This element allows you configure and inject a custom interceptor.
+ * This tag may appear multiple times."
*
* @author Mircea.Markus at jboss.com
* @author Vladimir Blagojevic
@@ -66,30 +66,30 @@
protected boolean isLast;
/** @configRef desc="A position at which to place this interceptor in the chain, with 0 being the first position.
- * Note that this attribute is mutually exclusive with position, before and after." */
+ * Note that this attribute is mutually exclusive with 'position', 'before' and 'after'." */
@XmlAttribute
protected Integer index = -1;
/** @configRef desc="Will place the new interceptor directly after the instance of the named interceptor which is
* specified via its fully qualified class name. Note that this attribute is mutually exclusive with
- * position, before and index." */
+ * 'position', 'before' and 'index'." */
@XmlAttribute
protected String after;
/** @configRef desc="Will place the new interceptor directly before the instance of the named interceptor which is
* specified via its fully qualified class name.. Note that this attribute is mutually exclusive with
- * position, after and index." */
+ * 'position', 'after' and 'index'." */
@XmlAttribute
protected String before;
- /** @configRef desc="A position at which to place this interceptor in the chain. First is the first interceptor
- * encountered when an invocation is made on the cache, last is the last interceptor before the call is
- * passed on to the data structure. Note that this attribute is mutually exclusive with before, after
- * and index." */
+ /** @configRef desc="A position at which to place this interceptor in the chain. FIRST is the first interceptor
+ * encountered when an invocation is made on the cache, LAST is the last interceptor before the call is
+ * passed on to the data structure. Note that this attribute is mutually exclusive with 'before', 'after'
+ * and 'index'." */
@XmlAttribute
protected Position position;
- /** @configRef name="class",desc="Fully qualified intereceptor class name which must extend CommandInterceptor." */
+ /** @configRef name="class",desc="Fully qualified intereceptor class name which must extend org.infinispan.interceptors.base.CommandInterceptor." */
@XmlAttribute(name="class")
protected String className;
Modified: trunk/core/src/main/java/org/infinispan/config/GlobalConfiguration.java
===================================================================
--- trunk/core/src/main/java/org/infinispan/config/GlobalConfiguration.java 2009-11-12 12:56:26 UTC (rev 1150)
+++ trunk/core/src/main/java/org/infinispan/config/GlobalConfiguration.java 2009-11-12 13:56:35 UTC (rev 1151)
@@ -32,7 +32,7 @@
* provide meta data for configuration file XML schema generation. Please modify these annotations
* and Java element types they annotate with utmost understanding and care.
*
- * @configRef name="global",desc="Defines global configuration shared among all cache instances."
+ * @configRef name="global",desc="Defines global settings shared among all cache instances created by a single CacheManager."
*
* @author Manik Surtani
* @author Vladimir Blagojevic
@@ -462,10 +462,10 @@
}
/**
- * @configRef name="asyncListenerExecutor",desc="Executor for listeners."
- * @configRef name="asyncTransportExecutor",desc="Transport executor."
- * @configRef name="evictionScheduledExecutor",desc="Eviction executor."
- * @configRef name="replicationQueueScheduledExecutor",desc="Executor for replication."
+ * @configRef name="asyncListenerExecutor",desc="Configuration for the executor service used to emit notifications to asynchronous listeners."
+ * @configRef name="asyncTransportExecutor",desc="Configuration for the executor service used for asynchronous work on the Transport, including asynchronous marshalling and Cache 'async operations' such as Cache.putAsync()."
+ * @configRef name="evictionScheduledExecutor",desc="Configuration for the scheduled executor service used to periodically run eviction cleanup tasks."
+ * @configRef name="replicationQueueScheduledExecutor",desc="Configuration for the scheduled executor service used to periodically flush replication queues, used if asynchronous clustering is enabled along with useReplQueue being set to true."
*/
@XmlAccessorType(XmlAccessType.PROPERTY)
public static class FactoryClassWithPropertiesType extends AbstractConfigurationBeanWithGCR {
@@ -473,13 +473,13 @@
/** The serialVersionUID */
private static final long serialVersionUID = 7625606997888180254L;
- /** @configRef desc="Executor fully qualified class name. It must implement org.infinispan.executors.ExecutorFactory" */
+ /** @configRef desc="Fully qualified class name of the ExecutorFactory (or ScheduledExecutorFactory) to use. Must implement org.infinispan.executors.ExecutorFactory (or ScheduledExecutorFactory), and defaults to org.infinispan.executors.DefaultExecutorFactory (or DefaultScheduledExecutorFactory)" */
@XmlAttribute
protected String factory;
/**
- * @configPropertyRef name="maxThreads",desc="Number of threads for this executor"
- * @configPropertyRef name="threadNamePrefix",desc="Name prefix for threads created in this executor"
+ * @configPropertyRef name="maxThreads",desc="Maximum number of threads for this executor."
+ * @configPropertyRef name="threadNamePrefix",desc="Thread name prefix for threads created by this executor."
* */
@XmlElement(name="properties")
protected TypedProperties properties = EMPTY_PROPERTIES;
@@ -517,7 +517,7 @@
}
/**
- * @configRef name="transport",desc="This element configures the transport used to communicate accross the cluster."
+ * @configRef name="transport",desc="This element configures the transport used for network communications across the cluster."
*/
@XmlAccessorType(XmlAccessType.PROPERTY)
public static class TransportType extends AbstractConfigurationBeanWithGCR {
@@ -525,19 +525,18 @@
/** The serialVersionUID */
private static final long serialVersionUID = -4739815717370060368L;
- /** @configRef desc="Cluster name where all cache instances defined are connected" */
+ /** @configRef desc="This defines the name of the cluster. Nodes only connect to clusters sharing the same name." */
protected String clusterName = "Infinispan-Cluster";
- /** @configRef desc="Cluster-wide synchronization timeout for locks that are aware of block and unblock commands
- * issued across a cluster and sub-phases such as a start processing" */
+ /** @configRef desc="Cluster-wide synchronization timeout for locks. Used to coordinate changes in cluster membership." */
protected Long distributedSyncTimeout = 60000L; // default
- /** @configRef desc="Fully qualified name of a class that implements network transport which must
+ /** @configRef desc="Fully qualified name of a class that represents a network transport. Must
* implement org.infinispan.remoting.transport.Transport"*/
protected String transportClass = null; // this defaults to a non-clustered cache.
/**
- * @configRef desc="Node name for the underlying transport channel"
+ * @configRef desc="Name of the current node. This is a friendly name to make logs, etc. make more sense. Defaults to a combination of host name and a random number (to differentiate multiple nodes on the same host)"
*/
protected String nodeName = null;
@@ -604,11 +603,13 @@
/** The serialVersionUID */
private static final long serialVersionUID = -925947118621507282L;
- /** @configRef desc="Fully qualified name of a class that marshalls objects between cache nodes. It must
+ /** @configRef desc="Fully qualified name of the marshaller to use. It must
* implement org.infinispan.marshall.Marshaller."*/
protected String marshallerClass = VersionAwareMarshaller.class.getName(); // the default
- /** @configRef desc="Marshalling serialization version."*/
+ /** @configRef desc="Largest allowable version to use when marshalling internal state. Set this to the lowest version
+ * cache instance in your cluster to ensure compatibility of communications. However, setting this
+ * too low will mean you lose out on the benefit of improvements in newer versions of the marshaller."*/
protected String version = Version.getMajorVersion();
public SerializationType() {
@@ -648,12 +649,12 @@
/** @configRef desc="JMX domain name where all relevant JMX exposed objects will be bound" */
protected String jmxDomain = "infinispan";
- /** @configRef desc="Fully qualified name of class that will attempt to find JMX MBean server" */
+ /** @configRef desc="Fully qualified name of class that will attempt to locate a JMX MBean server to bind to" */
protected String mBeanServerLookup = PlatformMBeanServerLookup.class.getName();
/** @configRef desc="If true, multiple cache manager instances could be configured under the same configured
* JMX domain. Each cache manager will in practice use a different JMX domain that has been
- * calculated based on the configured one by adding an index number to it." */
+ * calculated based on the configured one by adding an incrementing index to it." */
protected Boolean allowDuplicateDomains = false;
@XmlAttribute
@@ -687,7 +688,7 @@
/**
*
- * @configRef name="shutdown",desc=" This element specifies behavior when the cache shuts down."
+ * @configRef name="shutdown",desc=" This element specifies behavior when the JVM running the cache instance shuts down."
*/
@XmlAccessorType(XmlAccessType.PROPERTY)
public static class ShutdownType extends AbstractConfigurationBeanWithGCR {
Modified: trunk/core/src/main/java/org/infinispan/config/InfinispanConfiguration.java
===================================================================
--- trunk/core/src/main/java/org/infinispan/config/InfinispanConfiguration.java 2009-11-12 12:56:26 UTC (rev 1150)
+++ trunk/core/src/main/java/org/infinispan/config/InfinispanConfiguration.java 2009-11-12 13:56:35 UTC (rev 1151)
@@ -60,7 +60,7 @@
* file XML schema generation. Please modify these annotations and Java element types they annotate with utmost
* understanding and care.
*
- * @configRef name="infinispan",desc="Root of Infinispan configuration."
+ * @configRef name="infinispan",desc="The root element of an Infinispan configuration. This element can be empty for sensible defaults throughout, however that would only give you the most basic of local, non-clustered caches."
*
* @author Vladimir Blagojevic
* @since 4.0
More information about the infinispan-commits
mailing list