/*

 * 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 GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package java.lang.management;

import javax.management.openmbean.CompositeData;

import sun.management.MemoryUsageCompositeData;

/**

 * A {@code MemoryUsage} object represents a snapshot of memory usage.

 * Instances of the {@code MemoryUsage} class are usually constructed

 * by methods that are used to obtain memory usage

 * information about individual memory pool of the Java virtual machine or

 * the heap or non-heap memory of the Java virtual machine as a whole.

 *

 * <p> A {@code MemoryUsage} object contains four values:

 * <tr>

 *      the Java virtual machine requests from the operating system

 *      for memory management during startup.  The Java virtual machine

 *      may request additional memory from the operating system and

 *      may also release memory to the system over time.

 *      The value of {@code init} may be undefined.

 * </td>

 * </tr>

 * <tr>

 * </td>

 * </tr>

 * <tr>

 *      guaranteed to be available for use by the Java virtual machine.

 *      The amount of committed memory may change over time (increase

 *      or decrease).  The Java virtual machine may release memory to

 *      the system and {@code committed} could be less than {@code init}.

 *      {@code committed} will always be greater than

 *      or equal to {@code used}.

 * </td>

 * </tr>

 * <tr>

 *      that can be used for memory management. Its value may be undefined.

 *      The maximum amount of memory may change over time if defined.

 *      The amount of used and committed memory will always be less than

 *      or equal to {@code max} if {@code max} is defined.

 *      A memory allocation may fail if it attempts to increase the

 *      used memory such that {@code used > committed} even

 *      if {@code used <= max} would still be true (for example,

 *      when the system is low on virtual memory).

 * </td>

 * </tr>

 * </table>

 *

 * Below is a picture showing an example of a memory pool:

 *

 * <pre>

 *        +----------------------------------------------+

 *        +////////////////           |                  +

 *        +////////////////           |                  +

 *        +----------------------------------------------+

 *

 *        |--------|

 *           init

 *        |---------------|

 *               used

 *        |---------------------------|

 *                  committed

 *        |----------------------------------------------|

 *                            max

 * </pre>

 *

 * <h3>MXBean Mapping</h3>

 * {@code MemoryUsage} is mapped to a {@link CompositeData CompositeData}

 * with attributes as specified in the {@link #from from} method.

 *

 * @author   Mandy Chung

 * @since   1.5

 */

public class MemoryUsage {

    private final long init;

    private final long used;

    private final long committed;

    private final long max;

    /**

     * Constructs a {@code MemoryUsage} object.

     *

     * @param init      the initial amount of memory in bytes that

     *                  the Java virtual machine allocates;

     *                  or {@code -1} if undefined.

     * @param used      the amount of used memory in bytes.

     * @param committed the amount of committed memory in bytes.

     * @param max       the maximum amount of memory in bytes that

     *                  can be used; or {@code -1} if undefined.

     *

     * @throws IllegalArgumentException if

     * <ul>

     * <li> the value of {@code init} or {@code max} is negative

     *      but not {@code -1}; or</li>

     * <li> the value of {@code used} or {@code committed} is negative;

     *      or</li>

     * <li> {@code used} is greater than the value of {@code committed};

     *      or</li>

     * <li> {@code committed} is greater than the value of {@code max}

     *      {@code max} if defined.</li>

     * </ul>

     */

    public MemoryUsage(long init,

                       long used,

                       long committed,

                       long max) {

        if (init < -1) {

            throw new IllegalArgumentException( "init parameter = " +

                init + " is negative but not -1.");

        }

        if (max < -1) {

            throw new IllegalArgumentException( "max parameter = " +

                max + " is negative but not -1.");

        }

        if (used < 0) {

            throw new IllegalArgumentException( "used parameter = " +

                used + " is negative.");

        }

        if (committed < 0) {

            throw new IllegalArgumentException( "committed parameter = " +

                committed + " is negative.");

        }

        if (used > committed) {

            throw new IllegalArgumentException( "used = " + used +

                " should be <= committed = " + committed);

        }

        if (max >= 0 && committed > max) {

            throw new IllegalArgumentException( "committed = " + committed +

                " should be < max = " + max);

        }

        this.init = init;

        this.used = used;

        this.committed = committed;

        this.max = max;

    }

    /**

     * Constructs a {@code MemoryUsage} object from a

     * {@link CompositeData CompositeData}.

     */

    private MemoryUsage(CompositeData cd) {

        // validate the input composite data

        MemoryUsageCompositeData.validateCompositeData(cd);

        this.init = MemoryUsageCompositeData.getInit(cd);

        this.used = MemoryUsageCompositeData.getUsed(cd);

        this.committed = MemoryUsageCompositeData.getCommitted(cd);

        this.max = MemoryUsageCompositeData.getMax(cd);

    }

    /**

     * Returns the amount of memory in bytes that the Java virtual machine

     * initially requests from the operating system for memory management.

     * This method returns {@code -1} if the initial memory size is undefined.

     *

     * @return the initial size of memory in bytes;

     * {@code -1} if undefined.

     */

    public long getInit() {

        return init;

    }

    /**

     * Returns the amount of used memory in bytes.

     *

     * @return the amount of used memory in bytes.

     *

     */

    public long getUsed() {

        return used;

    };

    /**

     * Returns the amount of memory in bytes that is committed for

     * the Java virtual machine to use.  This amount of memory is

     * guaranteed for the Java virtual machine to use.

     *

     * @return the amount of committed memory in bytes.

     *

     */

    public long getCommitted() {

        return committed;

    };

    /**

     * Returns the maximum amount of memory in bytes that can be

     * used for memory management.  This method returns {@code -1}

     * if the maximum memory size is undefined.

     *

     * <p> This amount of memory is not guaranteed to be available

     * for memory management if it is greater than the amount of

     * committed memory.  The Java virtual machine may fail to allocate

     * memory even if the amount of used memory does not exceed this

     * maximum size.

     *

     * @return the maximum amount of memory in bytes;

     * {@code -1} if undefined.

     */

    public long getMax() {

        return max;

    };

    /**

     * Returns a descriptive representation of this memory usage.

     */

    public String toString() {

        StringBuilder buf = new StringBuilder();

        buf.append("init = " + init + "(" + (init >> 10) + "K) ");

        buf.append("used = " + used + "(" + (used >> 10) + "K) ");

        buf.append("committed = " + committed + "(" +

                   (committed >> 10) + "K) " );

        buf.append("max = " + max + "(" + (max >> 10) + "K)");

        return buf.toString();

    }

    /**

     * Returns a {@code MemoryUsage} object represented by the

     * given {@code CompositeData}. The given {@code CompositeData}

     * must contain the following attributes:

     *

     * <blockquote>

     * <tr>

     * </tr>

     * <tr>

     *   <td>init</td>

     *   <td>{@code java.lang.Long}</td>

     * </tr>

     * <tr>

     *   <td>used</td>

     *   <td>{@code java.lang.Long}</td>

     * </tr>

     * <tr>

     *   <td>committed</td>

     *   <td>{@code java.lang.Long}</td>

     * </tr>

     * <tr>

     *   <td>max</td>

     *   <td>{@code java.lang.Long}</td>

     * </tr>

     * </table>

     * </blockquote>

     *

     * @param cd {@code CompositeData} representing a {@code MemoryUsage}

     *

     * @throws IllegalArgumentException if {@code cd} does not

     *   represent a {@code MemoryUsage} with the attributes described

     *   above.

     *

     * @return a {@code MemoryUsage} object represented by {@code cd}

     *         if {@code cd} is not {@code null};

     *         {@code null} otherwise.

     */

    public static MemoryUsage from(CompositeData cd) {

        if (cd == null) {

            return null;

        }

        if (cd instanceof MemoryUsageCompositeData) {

            return ((MemoryUsageCompositeData) cd).getMemoryUsage();

        } else {

            return new MemoryUsage(cd);

        }

    }

}