lightning-core/src/main/java/org/apache/directmemory/lightning/Lightning.java

/*
 * 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
 *
 * 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.directmemory.lightning;

import java.io.File;
import java.lang.annotation.Annotation;
import java.util.Arrays;
import java.util.HashSet;
import java.util.Set;

import org.apache.directmemory.lightning.ClassComparisonStrategy;
import org.apache.directmemory.lightning.SerializationStrategy;
import org.apache.directmemory.lightning.Serializer;
import org.apache.directmemory.lightning.base.DefaultValueNullableEvaluator;
import org.apache.directmemory.lightning.configuration.SerializerDefinition;
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
{

    private Lightning()
    {
    }

    /**
     * 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 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 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 Serializer createSerializer( Iterable<? extends SerializerDefinition> serializerDefinitions )
    {
        return new Builder().serializerDefinitions( serializerDefinitions ).build();
    }

    public static class Builder
    {

        private Set<SerializerDefinition> serializerDefinitions = new HashSet<SerializerDefinition>();

        private SerializationStrategy serializationStrategy = SerializationStrategy.SpeedOptimized;

        private Class<? extends Annotation> attributeAnnotation = null;

        private ClassComparisonStrategy classComparisonStrategy = ClassComparisonStrategy.LightningChecksum;

        private ValueNullableEvaluator valueNullableEvaluator = new DefaultValueNullableEvaluator();

        private File debugCacheDirectory = null;

        private Logger logger = new NoOpLogger();

        private Builder()
        {
        }

        /**
         * 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 )
            {
                this.serializerDefinitions.add( serializerDefinition );
            }
            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();
        }
    }

}