Added more javadoc
git-svn-id: https://svn.apache.org/repos/asf/directmemory/lightning/trunk@1398082 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/lightning-core/src/main/java/org/apache/directmemory/lightning/ClassComparisonStrategy.java b/lightning-core/src/main/java/org/apache/directmemory/lightning/ClassComparisonStrategy.java
index 1268095..673b465 100644
--- a/lightning-core/src/main/java/org/apache/directmemory/lightning/ClassComparisonStrategy.java
+++ b/lightning-core/src/main/java/org/apache/directmemory/lightning/ClassComparisonStrategy.java
@@ -19,8 +19,21 @@
package org.apache.directmemory.lightning;
/**
+ * <p>
* Defines the comparison strategy of classes between different serializers. The standard strategy of Java is
* SerialVersionUID but Lightning has some lighter algorithm which only takes properties into account.
+ * </p>
+ * <p>
+ * {@link #LightningChecksum} is a lightweight checksum only taking the defined attributes into account and is pretty
+ * insensitive to other changes in classes but adding / removing of attributes is not supported. This strategy is used
+ * by default.<br>
+ * {@link #SerialVersionUID} is using the standard Java serialVersionUID fields (or if not provided calculates it's
+ * value from the given class). Using this value you can force Lightning to see different versions of a class to be
+ * compatible but only adding attributes in newer class versions is supported.<br>
+ * {@link #SkipComparison} skips any kind of comparison check and can be used when user provided marshallers can handle
+ * different versions of classes. This could be used to implement some kind of schema evolution but is only recommended
+ * for export use.
+ * </p>
*/
public enum ClassComparisonStrategy
{
diff --git a/lightning-core/src/main/java/org/apache/directmemory/lightning/Lightning.java b/lightning-core/src/main/java/org/apache/directmemory/lightning/Lightning.java
index 6ff3d96..9ecaa31 100644
--- a/lightning-core/src/main/java/org/apache/directmemory/lightning/Lightning.java
+++ b/lightning-core/src/main/java/org/apache/directmemory/lightning/Lightning.java
@@ -32,6 +32,7 @@
import org.apache.directmemory.lightning.internal.InternalSerializerCreator;
import org.apache.directmemory.lightning.logging.Logger;
import org.apache.directmemory.lightning.logging.NoOpLogger;
+import org.apache.directmemory.lightning.metadata.PropertyDescriptor;
import org.apache.directmemory.lightning.metadata.ValueNullableEvaluator;
public final class Lightning
@@ -41,16 +42,37 @@
{
}
+ /**
+ * Creates a new Lightning {@link Builder} for more complex configuration of a new {@link Serializer} instance.
+ *
+ * @return A Builder instance for configuring a new {@link Serializer} instance.
+ */
public static final Builder newBuilder()
{
return new Builder();
}
+ /**
+ * Provides fast configuration of a new {@link Serializer} instance by just providing a bunch of
+ * {@link SerializerDefinition}s.
+ *
+ * @param serializerDefinitions The {@link SerializerDefinition}s to use for configuring the {@link Serializer}
+ * instance
+ * @return A new {@link Serializer} instance configured using the given {@link SerializerDefinition}s
+ */
public static final Serializer createSerializer( SerializerDefinition... serializerDefinitions )
{
return createSerializer( Arrays.asList( serializerDefinitions ) );
}
+ /**
+ * Provides fast configuration of a new {@link Serializer} instance by just providing a bunch of
+ * {@link SerializerDefinition}s.
+ *
+ * @param serializerDefinitions The {@link SerializerDefinition}s to use for configuring the {@link Serializer}
+ * instance
+ * @return A new {@link Serializer} instance configured using the given {@link SerializerDefinition}s
+ */
public static final Serializer createSerializer( Iterable<? extends SerializerDefinition> serializerDefinitions )
{
return new Builder().serializerDefinitions( serializerDefinitions ).build();
@@ -77,35 +99,99 @@
{
}
+ /**
+ * Defines a basic {@link Annotation} to describe an class attribute (instance field) as an attribute (de-)
+ * serialized by Lightning.
+ *
+ * @param attributeAnnotation {@link Annotation} to describe a field as an serializable attribute
+ * @return The actual builder instance for chaining
+ */
public Builder describesAttributs( Class<? extends Annotation> attributeAnnotation )
{
this.attributeAnnotation = attributeAnnotation;
return this;
}
+ /**
+ * Defines a directory where generated classes should be stored for debug purpose.
+ *
+ * @param debugCacheDirectory Directory for storing generated class files
+ * @return The actual builder instance for chaining
+ */
public Builder debugCacheDirectory( File debugCacheDirectory )
{
this.debugCacheDirectory = debugCacheDirectory;
return this;
}
+ /**
+ * <p>
+ * The strategy to be used for serializing objects. There are two different strategies provided:
+ * </p>
+ * <p>
+ * {@link SerializationStrategy#SpeedOptimized} does not look for same instances to be (de-) serialized only
+ * once but written many times to the stream. This maybe needs more bytes in the stream but is faster because no
+ * additional metadata needs to be managened.<br>
+ * {@link SerializationStrategy#SizeOptimized} manages metadata of the allready serialized data and will not
+ * serialize them again (but just writing an object-id to the stream). This will likely save bytes but managing
+ * the metadata is using some time.
+ * </p>
+ *
+ * @param serializationStrategy The strategy to be used when serialize data
+ * @return The actual builder instance for chaining
+ */
public Builder serializationStrategy( SerializationStrategy serializationStrategy )
{
this.serializationStrategy = serializationStrategy;
return this;
}
+ /**
+ * <p>
+ * The strategy to be used to compare class informations of different serializers (for example in clustered
+ * environments). Lightning offers three different strategies:
+ * </p>
+ * <p>
+ * {@link ClassComparisonStrategy#LightningChecksum} is a lightweight checksum only taking the defined
+ * attributes into account and is pretty insensitive to other changes in classes but adding / removing of
+ * attributes is not supported. This strategy is used by default.<br>
+ * {@link ClassComparisonStrategy#SerialVersionUID} is using the standard Java serialVersionUID fields (or if
+ * not provided calculates it's value from the given class). Using this value you can force Lightning to see
+ * different versions of a class to be compatible but only adding attributes in newer class versions is
+ * supported.<br>
+ * {@link ClassComparisonStrategy#SkipComparison} skips any kind of comparison check and can be used when user
+ * provided marshallers can handle different versions of classes. This could be used to implement some kind of
+ * schema evolution but is only recommended for export use.
+ * </p>
+ *
+ * @param classComparisonStrategy The strategy to be used when compare class information
+ * @return The actual builder instance for chaining
+ */
public Builder classComparisonStrategy( ClassComparisonStrategy classComparisonStrategy )
{
this.classComparisonStrategy = classComparisonStrategy;
return this;
}
+ /**
+ * Defines a bunch of {@link SerializerDefinition}s to be used by the final {@link Serializer}. Multiple calls
+ * of this methods are possible.
+ *
+ * @param serializerDefinitions The {@link SerializerDefinition}s to use for configuring the {@link Serializer}
+ * @return The actual builder instance for chaining
+ */
public Builder serializerDefinitions( SerializerDefinition... serializerDefinitions )
{
return serializerDefinitions( Arrays.asList( serializerDefinitions ) );
}
+ /**
+ * Defines a bunch of {@link SerializerDefinition}s to be used by the final {@link Serializer}. Multiple calls
+ * of this methods are possible.
+ *
+ * @param serializerDefinitions The {@link SerializerDefinition}s to use for configuring the {@link Serializer}
+ * @return The actual builder instance for chaining
+ */
public Builder serializerDefinitions( Iterable<? extends SerializerDefinition> serializerDefinitions )
{
for ( SerializerDefinition serializerDefinition : serializerDefinitions )
@@ -115,18 +201,42 @@
return this;
}
+ /**
+ * Defines a user implementation of the {@link ValueNullableEvaluator} interface which is used to evaluate if a
+ * {@link PropertyDescriptor} defined attribute can be null. A custom implementation should extends
+ * {@link DefaultValueNullableEvaluator} to inherit all standard behavior. Custom implementations are needed to
+ * give Lightning an information if a value is nullable when using customized attribute annotations.
+ *
+ * @param valueNullableEvaluator A {@link ValueNullableEvaluator} implementation to evaluate a value is nullable
+ * or not
+ * @return The actual builder instance for chaining
+ */
public Builder setValueNullableEvaluator( ValueNullableEvaluator valueNullableEvaluator )
{
this.valueNullableEvaluator = valueNullableEvaluator;
return this;
}
+ /**
+ * A custom logger implementation can be given to the {@link Serializer} to redirect logging output to any other
+ * logging framework like slf4j, log4j, java.util.Logging or even a custom framework.
+ *
+ * @param logger The {@link Logger} implementation to be used for logging events.
+ * @return The actual builder instance for chaining
+ */
public Builder logger( Logger logger )
{
this.logger = logger;
return this;
}
+ /**
+ * Finally builds the {@link Serializer} using the given configurations. In that step all {@link Marshaller}
+ * implementations (that are not provided by the user) are autogenerated using the given
+ * {@link SerializerDefinition}s.
+ *
+ * @return The configured and ready to use {@link Serializer}
+ */
public Serializer build()
{
return new InternalSerializerCreator().setLogger( logger ).setSerializationStrategy( serializationStrategy ).setClassComparisonStrategy( classComparisonStrategy ).setAttributeAnnotation( attributeAnnotation ).setDebugCacheDirectory( debugCacheDirectory ).setValueNullableEvaluator( valueNullableEvaluator ).addSerializerDefinitions( serializerDefinitions ).build();
