Oracle® Fusion Middleware C++ API Reference for Oracle Coherence
12c (12.2.1.2.0)
E77779-01

coherence/util/Objects.hpp

/*
* Objects.hpp
*
* Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.
*
* Oracle is a registered trademarks of Oracle Corporation and/or its
* affiliates.
*
* This software is the confidential and proprietary information of Oracle
* Corporation. You shall not disclose such confidential and proprietary
* information and shall use it only in accordance with the terms of the
* license agreement you entered into with Oracle.
*
* This notice may not be removed or altered.
*/
#ifndef COH_OBJECTS_HPP
#define COH_OBJECTS_HPP

#include "coherence/lang.ns"

#include "coherence/util/Comparator.hpp"

COH_OPEN_NAMESPACE2(coherence,util)

/**
 * This class consists of static {@code NULL}-safe or {@code NULL}-tolerant
 * utility methods for operating on Objects.
 *
 * @author phf  2015.07.10
 *
 * @since 12.2.1
 */
class COH_EXPORT Objects
    : public abstract_spec<Objects>
    {
    // ----- Objects interface ----------------------------------------------

    public:
        using Object::toString;

        /**
         * Returns the result of calling {@code toString} on the first
         * argument if the first argument is not {@code NULL} and returns
         * the second argument otherwise.
         *
         * @param v              an Object
         * @param vsNullDefault  string to return if the first argument is
         *                       {@code NULL}
         *
         * @return the result of calling {@code toString} on the first
         * argument if it is not {@code null} and the second argument
         * otherwise.
         *
         * @see Object#toString(Object)
         */
        static String::View toString(Object::View v, String::View vsNullDefault);

        /**
         * Returns 0 if the arguments are identical and {@code
         * vC->compare(vA, vB)} otherwise.
         * Consequently, if both arguments are {@code NULL} 0
         * is returned.
         *
         * Note that if one of the arguments is {@code NULL}, a {@code
         * NullPointerException} may or may not be thrown depending on
         * what ordering policy, if any, the Comparator
         * chooses to have for {@code NULL} values.
         *
         * @param vA  an Object
         * @param vB  an Object to be compared with {@code vA}
         * @param vC  the Comparator to compare the first two arguments
         *
         * @return 0 if the arguments are identical and
         *           {@code c->compare(vA, vB)} otherwise.
         *
         * @see Comparable
         * @see Comparator
         */
        static int32_t compare(Object::View vA, Object::View vB, Comparator::View vC);

        /**
         * Checks that the specified object reference is not {@code NULL}. This
         * method is designed primarily for doing parameter validation in methods
         * and constructors, as demonstrated below:
         * <blockquote><pre>
         * protected Foo(Bar::View vBar) {
         *     this.vBar = Objects::requireNonNull(vBar);
         * }
         * </pre></blockquote>
         *
         * @param oh the Object reference to check for nullity
         *
         * @return {@code oh} if not {@code NULL}
         *
         * @throws NullPointerException if {@code oh} is {@code NULL}
         */
        static Object::Holder requireNonNull(Object::Holder oh);

        /**
         * Checks that the specified Object reference is not {@code NULL} and
         * throws a customized NullPointerException if it is. This method
         * is designed primarily for doing parameter validation in methods and
         * constructors with multiple parameters, as demonstrated below:
         * <blockquote><pre>
         * protected Foo(Bar::View vBar, Baz::View vBaz) {
         *     this.vBar = Objects::requireNonNull(vBar, "vBar must not be null");
         *     this.vBaz = Objects::requireNonNull(vBaz, "vBaz must not be null");
         * }
         * </pre></blockquote>
         *
         * @param oh         the Object reference to check for nullity
         * @param vsMessage  detail message to be used in the event that a
         *                   NullPointerException is thrown
         *
         * @return {@code oh} if not {@code NULL}
         *
         * @throws NullPointerException if {@code oh} is {@code NULL}
         */
        static Object::Holder requireNonNull(Object::Holder oh, String::View vsMessage);

        /**
         * Returns {@code true} if the provided reference is {@code NULL} otherwise
         * returns {@code false}.
         *
         * @param v  an Object to be checked against {@code NULL}
         *
         * @return {@code true} if the provided reference is {@code NULL} otherwise
         *         {@code false}
         */
        static bool isNull(Object::View v);

        /**
         * Returns {@code true} if the provided reference is non-{@code NULL}
         * otherwise returns {@code false}.
         *
         * @param v  an Object to be checked against {@code NULL}
         *
         * @return {@code true} if the provided reference is non-{@code NULL}
         *         otherwise {@code false}
         */
        static bool nonNull(Object::View v);
    };

COH_CLOSE_NAMESPACE2

#endif // COH_OBJECTS_HPP

Copyright © 2000, 2016, Oracle and/or its affiliates. All rights reserved.