/*
 * Copyright (c) 2008, 2017 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0, which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the
 * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
 * version 2 with the GNU Classpath Exception, which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 */

package org.glassfish.grizzly.attributes;

AttributeBuilder is responsible for creating and indexing Attributes. For faster access to Attribute value, each Attribute has assigned index. AttributeBuilder is responsible to assign each Attribute unique index. 
Author:
Alexey Stashok
See Also:
DefaultAttributeBuilder/**
 * <tt>AttributeBuilder</tt> is responsible for creating and indexing
 * {@link Attribute}s.
 * For faster access to {@link Attribute} value, each {@link Attribute} has
 * assigned index. <tt>AttributeBuilder</tt> is responsible to assign each
 * {@link Attribute} unique index.
 *
 * @see DefaultAttributeBuilder
 * 
 * @author Alexey Stashok
 */
public interface AttributeBuilder {

    
 The default AttributeBuilder implementation used by all created builder instances. 

The default may be changed by setting the system property org.glassfish.grizzly.DEFAULT_ATTRIBUTE_BUILDER
with the fully qualified name of the class that implements the AttributeBuilder interface.  Note that this class must
be public and have a public no-arg constructor.

/**
     * <p>
     * The default {@link AttributeBuilder} implementation used by all created builder
     * instances.
     * </p>
     *
     * <p>
     * The default may be changed by setting the system property <code>org.glassfish.grizzly.DEFAULT_ATTRIBUTE_BUILDER</code>
     * with the fully qualified name of the class that implements the AttributeBuilder interface.  Note that this class must
     * be public and have a public no-arg constructor.
     * </p>
     */
    AttributeBuilder DEFAULT_ATTRIBUTE_BUILDER =
            AttributeBuilderInitializer.initBuilder();

    
Create Attribute with name
Params:
name – attribute name
Type parameters:
<T> – Type of attribute value
Returns:
Attribute/**
     * Create Attribute with name
     * 
     * @param <T> Type of attribute value
     * @param name attribute name

     * @return Attribute<T>
     */
    <T> Attribute<T> createAttribute(String name);

    
Create Attribute with name and default value
Params:
name – attribute name
defaultValue – attribute's default value
Type parameters:
<T> – Type of attribute value
Returns:
Attribute/**
     * Create Attribute with name and default value
     * 
     * @param <T> Type of attribute value
     * @param name attribute name
     * @param defaultValue attribute's default value
     * 
     * @return Attribute<T>
     */
    <T> Attribute<T> createAttribute(String name, T defaultValue);

    
Create Attribute with name and initializer, which will be called, if
Attribute's value is null on a AttributedObject
Params:
name – attribute name
initializer – NullaryFunction, which will be called, if Attribute's
                   value is null on a AttributedObject
Type parameters:
<T> – Type of attribute value
Returns:
Attribute/**
     * Create Attribute with name and initializer, which will be called, if
     * Attribute's value is null on a AttributedObject
     * 
     * @param <T> Type of attribute value
     * @param name attribute name
     * @param initializer NullaryFunction, which will be called, if Attribute's
     *                    value is null on a AttributedObject 
     * 
     * @return Attribute<T>
     */
    <T> Attribute<T> createAttribute(String name, org.glassfish.grizzly.utils.NullaryFunction<T> initializer);
    
    
Create Attribute with name and initializer, which will be called, if
Attribute's value is null on a AttributedObject
Params:
name – attribute name
initializer – NullaryFunction, which will be called, if Attribute's
                   value is null on a AttributedObject
Type parameters:
<T> – Type of attribute value
Returns:
Attribute
Deprecated:
pls. use createAttribute(String, NullaryFunction<Object>)./**
     * Create Attribute with name and initializer, which will be called, if
     * Attribute's value is null on a AttributedObject
     * 
     * @param <T> Type of attribute value
     * @param name attribute name
     * @param initializer NullaryFunction, which will be called, if Attribute's
     *                    value is null on a AttributedObject 
     * 
     * @return Attribute<T>
     * @deprecated pls. use {@link #createAttribute(java.lang.String, org.glassfish.grizzly.utils.NullaryFunction)}.
     */
    <T> Attribute<T> createAttribute(String name, NullaryFunction<T> initializer);

    
Creates and returns new thread-safe AttributeHolder 
Returns:
thread-safe AttributeHolder/**
     * Creates and returns new thread-safe {@link AttributeHolder}
     * 
     * @return thread-safe {@link AttributeHolder}
     */
    AttributeHolder createSafeAttributeHolder();
    
    
Creates and returns new non thread-safe AttributeHolder 
Returns:
non thread-safe AttributeHolder/**
     * Creates and returns new non thread-safe {@link AttributeHolder}
     * 
     * @return non thread-safe {@link AttributeHolder}
     */
    AttributeHolder createUnsafeAttributeHolder();
}