All Downloads are FREE. Search and download functionalities are using the official Maven repository.
  • Log In
  • Register

    • net.sf.javagimmicks.collections.transformer.package-info Maven / Gradle / Ivy

    /**
 * This package spans up the JavaGimmicks
 * transformation API, which allows to create instances of the
 * standard Java Collection API classes (and some more),
 * that internally work with another form of elements as
 * visible to the client. Let's use the terms
 * internal format and external format for this
 * two element formats.
 * 
    
 * For example, you can create a {@code List} which is
 * actually internally backed by a {@code List}. You 
 * wont't be aware of this fact and will think to work with
 * a {@code List}. You can add, remove, get or set
 * elements and of course iterate over them. The instance
 * you are working on will automatically take care of transforming
 * between the respective element types {@link java.lang.String} and
 * {@link java.lang.Integer} and the results of all operations will be
 * immediately visible in the internal {@link java.util.List}.
 * 
    
 * Additionally, you could also think of a {@code List}
 * which internally works with another {@code List}
 * but keeps the elements in the reverse character order (for
 * what reasons ever you like).
 * 
    
 * Of course, in order to be able to work with transforming
 * instances, you need to provide to them the transformation rules.
 * This you can do by writing a class that implements the
 * {@link net.sf.javagimmicks.collections.transformer.Transformer} or
 * {@link net.sf.javagimmicks.collections.transformer.BidiTransformer} interface
 * which are both contained in this API.
 * 
    
 * When providing a {@link net.sf.javagimmicks.collections.transformer.Transformer},
 * you will only be able to perform operations on the transforming instance that
 * do not need to convert from the external format to the internal
 * format. For example, you will be able to iterate over a
 * {@link java.util.List}, get elements, remove them or ask if they are
 * contained inside. But you will not be able to set or add elements
 * (neither on the {@link java.util.List} nor on any of its
 * {@link java.util.ListIterator}s. For more details, see below.
 * 
    
 * When providing a {@link net.sf.javagimmicks.collections.transformer.BidiTransformer},
 * all operations will be available and some operations will even be faster.
 * 
 * 
    Decorator methods in {@link net.sf.javagimmicks.collections.transformer.TransformerUtils}
    
 * This class provides a large number of methods {@code decorate()}
 * (and {@code decorateKeyBased()} and {@code decorateValueBased()}
 * for {@link java.util.Map}s) which can be used to create transformed instances
 * of a number of (generic) base classes by providing an instance of this
 * base class and one of {@link net.sf.javagimmicks.collections.transformer.Transformer} or
 * {@link net.sf.javagimmicks.collections.transformer.BidiTransformer}.
 * 
    
 * The resulting instance will implement the same interface (but
 * eventually with different type parameters) and additionally
 * {@link net.sf.javagimmicks.collections.transformer.Transforming} or
 * {@link net.sf.javagimmicks.collections.transformer.BidiTransforming}
 * (both depending on the provided transformation rule instance).
 * Furthermore, this instance
 * is completely backed on the the provided one and will contain
 * no data itself. Any changes on it will affect the internal one and
 * vice versa.
 * 
 * 
 * 
    Operations on a transformed {@link java.util.Iterator}
    
 * 
 *    
 *       
 *          
 *          
 *          
 *       
 *    
 *    
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *    
 * 
    OperationTransformerBidiTransformer
    hasNext()supported
    next()supported
    remove()supported
    
 * 
 *     
 * 
    Operations on a transformed {@link java.util.Collection}
    
 * 
 *    
 *       
 *          
 *          
 *          
 *       
 *    
 *    
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *    
 * 
    OperationTransformerBidiTransformer
    add()not supportedsupported
    addAll()not supportedsupported
    clear()supported
    contains()supported; needs {@code equals()} method
    containsAll()supported; needs {@code equals()} method
    isEmpty()supported
    iterator()supported; See {@code Iterator} operations
    remove()supported; needs {@code equals()} method
    removeAll()supported; needs {@code equals()} method
    retainAll()supported; needs {@code equals()} method
    size()supported
    toArray()supported
    
 * 
 *     
 * 
    Operations on a transformed {@link java.util.Set}
    
 * 
 *    
 *       
 *          
 *          
 *          
 *       
 *    
 *    
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *    
 * 
    OperationTransformerBidiTransformer
    add()not supportedsupported
    addAll()not supportedsupported
    clear()supported
    contains()supported; needs {@code equals()} methodsupported; faster
    containsAll()supported; needs {@code equals()} methodsupported; faster
    isEmpty()supported
    iterator()supported; See {@code Iterator} operations
    remove()supported; needs {@code equals()} methodsupported; faster
    removeAll()supported; needs {@code equals()} methodsupported; faster
    retainAll()supported; needs {@code equals()} methodsupported; faster
    size()supported
    toArray()supported
    
 * 
 *     
 * 
    Operations on a transformed {@link java.util.SortedSet}
    
 * 
 *    
 *       
 *          
 *          
 *          
 *       
 *    
 *    
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *    
 * 
    OperationTransformerBidiTransformer
    {@link java.util.Set} operationsSee table for {@code Set} operations
    comparator()not supportedsupported
    first()supported
    headSet()not supportedsupported
    last()supported
    subSet()not supportedsupported
    tailSet()not supportedsupported
    
 * 
 *     
 * 
    Operations on a transformed {@link java.util.NavigableSet}
    
 * 
 *    
 *       
 *          
 *          
 *          
 *       
 *    
 *    
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *    
 * 
    OperationTransformerBidiTransformer
    {@link java.util.Set} operationsSee table for {@code Set} operations
    {@link java.util.SortedSet} operationsSee table for {@code SortedSet} operations
    ceiling()not supportedsupported
    descendingIterator()supported
    descendingSet()supported
    floor()not supportedsupported
    headSet()not supportedsupported
    higher()not supportedsupported
    lower()not supportedsupported
    pollFirst()supported
    pollLast()supported
    subSet()not supportedsupported
    tailSet()not supportedsupported
    
 * 
 *     
 * 
    Operations on a transformed {@link java.util.ListIterator}
    
 * 
 *    
 *       
 *          
 *          
 *          
 *       
 *    
 *    
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *    
 * 
    OperationTransformerBidiTransformer
    {@link java.util.Iterator} operationsSee table for {@code Iterator} operations
    add()not supportedsupported
    hasPrevious()supported
    nextIndex()supported
    previous()supported
    previousIndex()supported
    set()not supportedsupported
    
 * 
 *     
 * 
    Operations on a transformed {@link java.util.List}
    
 * 
 *    
 *       
 *          
 *          
 *          
 *       
 *    
 *    
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *       
 *          
 *          
 *          
 *       
 *       
 *          
 *          
 *       
 *    
 * 
    OperationTransformerBidiTransformer
    {@link java.util.Collection} operationsSee table for {@code Collection} operations
    add()not supportedsupported
    addAll()not supportedsupported
    get()supported
    indexOf()supported; needs {@code equals()} method
    lastIndexOf()supported; needs {@code equals()} method
    listIterator()supported; See {@code ListIterator} operations
    remove()supported
    set()not supportedsupported
    subList()supported (with same behaviour)
    
 * 
 * @author Michael Scholz
 */
package net.sf.javagimmicks.collections.transformer;




    © 2015 - 2025 Weber Informatics LLC | Privacy Policy