craterdog.collections.abstractions.SortableCollection Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of java-collection-framework Show documentation
A set of interfaces and classes that define a Java collection framework.
There is a newer version: 3.18
Show newest version
/************************************************************************
 * Copyright (c) Crater Dog Technologies(TM).  All Rights Reserved.     *
 ************************************************************************
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.        *
 *                                                                      *
 * This code is free software; you can redistribute it and/or modify it *
 * under the terms of The MIT License (MIT), as published by the Open   *
 * Source Initiative. (See http://opensource.org/licenses/MIT)          *
 ************************************************************************/
package craterdog.collections.abstractions;

import craterdog.collections.primitives.MergeSorter;
import craterdog.collections.primitives.RandomSorter;
import craterdog.core.Manipulator;
import craterdog.utils.NaturalComparator;
import java.util.Comparator;
import org.slf4j.ext.XLogger;
import org.slf4j.ext.XLoggerFactory;


/**
 * This abstract class defines the invariant methods that all sortable collections must inherit.
 * A sortable collection allows the order of its elements to be determined externally.  By
 * default, the elements will be placed in the order in which they were added to the collection.
 * Additionally, the elements can be sorted in various ways depending on a specified sorting
 * algorithm and comparison function.
 *
 * @author Derk Norton
 * @param  The type of element managed by the collection.
 */
public abstract class SortableCollection extends OpenCollection {

    static private final XLogger logger = XLoggerFactory.getXLogger(SortableCollection.class);


    /**
     * This method shuffles the elements in the collection using a randomizing algorithm.
     */
    public void shuffleElements() {
        logger.entry();
        Sorter sorter = new RandomSorter<>();
        sorter.sortCollection(this);
        logger.exit();
    }


    /**
     * This method sorts the elements in the collection using the default (merge) sorting
     * algorithm and the elements' compareTo method. It provides an easy way
     * to sort a collection using its natural ordering.
     */
    public void sortElements() {
        logger.entry();
        Sorter sorter = new MergeSorter<>();
        Comparator comparator = new NaturalComparator<>();
        sorter.sortCollection(this, comparator);
        logger.exit();
    }


    /**
     * This method sorts the elements in the collection using the default (merge) sorting
     * algorithm and the specified comparison function.
     *
     * @param comparator The desired comparison function.
     */
    public void sortElements(Comparator comparator) {
        logger.entry(comparator);
        Sorter sorter = new MergeSorter<>();
        sorter.sortCollection(this, comparator);
        logger.exit();
    }


    /**
     * This method sorts the elements in the collection using the specified sorting
     * algorithm and the specified comparison function.
     *
     * @param sorter The desired sorting algorithm.
     * @param comparator The desired comparison function.
     */
    public void sortElements(Sorter sorter, Comparator comparator) {
        logger.entry(sorter, comparator);
        sorter.sortCollection(this, comparator);
        logger.exit();
    }


    /**
     * This method creates a new default manipulator for the collection.
     *
     * @return The new manipulator.
     */
    public abstract Manipulator createManipulator();

}