/**

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 2013-2014 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Oracle designates this

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

 * by Oracle in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * Contributor(s):

 *

 * The Original Software is NetBeans. The Initial Developer of the Original

 * Software is Oracle. Portions Copyright 2013-2014 Oracle. All Rights Reserved.

 *

 * If you wish your version of this file to be governed by only the CDDL

 * or only the GPL Version 2, indicate your decision by adding

 * "[Contributor] elects to include this software in this distribution

 * under the [CDDL or GPL Version 2] license." If you do not indicate a

 * single choice of license, a recipient has the option to distribute

 * your version of this file under either the CDDL, the GPL Version 2 or

 * to extend the choice of license to its licensees as provided above.

 * However, if you add GPL Version 2 code and therefore, elected the GPL

 * Version 2 license, then the option applies only if the new code is

 * made subject to such option by the copyright holder.

 */

package org.netbeans.html.json.spi;

import java.util.ArrayList;

import java.util.Collection;

import java.util.List;

import net.java.html.BrwsrCtx;

import net.java.html.json.ComputedProperty;

import net.java.html.json.Model;

import org.netbeans.html.json.impl.Bindings;

import org.netbeans.html.json.impl.JSON;

import org.netbeans.html.json.impl.JSON.WS;

import org.netbeans.html.json.impl.JSONList;

import org.netbeans.html.json.impl.PropertyBindingAccessor;

import org.netbeans.html.json.impl.RcvrJSON;

import org.netbeans.html.json.impl.RcvrJSON.MsgEvnt;

/** Object associated with one instance of a model generated by the

 * {@link Model} annotation. Contains methods the generated class can

 * use to communicate with behind the scene associated {@link Technology}.

 * Each {@link Proto} object is associated with <a href="http://wiki.apidesign.org/wiki/Singletonizer">

 * singletonizer</a>-like interface {@link Type} which provides the

 * associated {@link Technology} the necessary information about the

 * generated {@link Model} class.

 *

 * @author Jaroslav Tulach

 * @since 0.7

 */

public final class Proto {

    private final Object obj;

    private final Type type;

    private final net.java.html.BrwsrCtx context;

    private org.netbeans.html.json.impl.Bindings ko;

    private Observers observers;

    Proto(Object obj, Type type, BrwsrCtx context) {

        this.obj = obj;

        this.type = type;

        this.context = context;

    }

    /** Browser context this proto object and its associated model

     * are operating-in.

     *

     * @return the associated context

     */

    public BrwsrCtx getContext() {

        return context;

    }

    /** Acquires global lock to compute a {@link ComputedProperty derived property}

     * on this proto object. This proto object must not be locked yet. No

     * dependency tracking is performed.

     *

     * @throws IllegalStateException if already locked

     */

    public void acquireLock() throws IllegalStateException {

        acquireLock(null);

    }

    /** Acquires global lock to compute a {@link ComputedProperty derived property}

     * on this proto object. This proto object must not be locked yet. The

     * name of the property is used to track dependencies on own

     * properties of other proto objects - when they are changed, this

     * {@link #valueHasMutated(java.lang.String) property is changed too}.

     *

     * @param propName name of property we are about to compute

     * @throws IllegalStateException thrown when there is a cyclic

     *   call is detected

     * @since 0.9

     */

    public void acquireLock(String propName) throws IllegalStateException {

        Observers.beginComputing(this, propName);

    }

    /** A property on this proto object is about to be accessed. Verifies

     * whether this proto object is accessible - e.g. it has not been

     * {@link #acquireLock() locked yet}. If everything is OK, the

     * <code>propName</code> is recorded in the chain of dependencies

     * tracked by {@link #acquireLock(java.lang.String)} and watched by

     * {@link #valueHasMutated(java.lang.String)}.

     *

     * @param propName name of the property that is requested

     * @throws IllegalStateException if the model is locked

     * @since 0.9

     */

    public void accessProperty(String propName) throws IllegalStateException {

        Observers.accessingValue(this, propName);

    }

    /** Verifies the model is not locked otherwise throws an exception.

     * @throws IllegalStateException if the model is locked

     */

    public void verifyUnlocked() throws IllegalStateException {

        Observers.verifyUnlocked(this);

    }

    /** When modifications are over, the model is switched into

     * unlocked state by calling this method.

     */

    public void releaseLock() {

        Observers.finishComputing(this);

    }

    /** Whenever model changes a property. It should notify the

     * associated technology by calling this method.

     * Since 0.8.3: This method may be called by any thread - it reschedules

     * its actual execution into appropriate one by using

     * {@link BrwsrCtx#execute(java.lang.Runnable)}.

     *

     * @param propName name of the changed property

     */

    public void valueHasMutated(final String propName) {

        context.execute(new Runnable() {

            @Override

            public void run() {

                if (ko != null) {

                    ko.valueHasMutated(propName, null, null);

                }

                Observers.valueHasMutated(Proto.this, propName);

            }

        });

    }

    /** Whenever model changes a propertyit should notify the

     * associated technology. Either by calling this method

     * (if the new value is known and different to the old one) or

     * via (slightly ineffective) {@link #valueHasMutated(java.lang.String)}

     * method.

     * Since 0.8.3: This method may be called by any thread - it reschedules

     * its actual execution into appropriate one by using

     * {@link BrwsrCtx#execute(java.lang.Runnable)}.

     *

     * @param propName name of the changed property

     * @param oldValue provides previous value of the property

     * @param newValue provides new value of the property

     * @since 0.7.6

     */

    public void valueHasMutated(

        final String propName, final Object oldValue, final Object newValue

    ) {

        context.execute(new Runnable() {

            @Override

            public void run() {

                if (ko != null) {

                    ko.valueHasMutated(propName, oldValue, newValue);

                }

                Observers.valueHasMutated(Proto.this, propName);

            }

        });

    }

    /** Initializes the associated model in the current {@link #getContext() context}.

     * In case of <em>knockout.js</em> technology, applies given bindings

     * of the current model to the <em>body</em> element of the page.

     */

    public void applyBindings() {

        initBindings().applyBindings(null);

    }

    /** Initializes the associated model to the specified element's subtree.

     * The technology is taken from the current {@link #getContext() context} and

     * in case of <em>knockout.js</em> applies given bindings

     * of the current model to the element of the page with 'id' attribute

     * set to the specified <code>id</code> value.

     *

     * @param id the id of element to apply the binding to

     * @since 1.1

     * @see Technology.ApplyId

     */

    public void applyBindings(String id) {

        initBindings().applyBindings(id);

    }

    /** Invokes the provided runnable in the {@link #getContext() context}

     * of the browser. If the caller is already on the right thread, the

     * <code>run.run()</code> is invoked immediately and synchronously.

     * Otherwise the method returns immediately and the <code>run()</code>

     * method is performed later

     *

     * @param run the action to execute

     */

    public void runInBrowser(Runnable run) {

        context.execute(run);

    }

    /** Invokes the specified function index in the {@link #getContext() context}

     * of the browser. If the caller is already on the right thread, the

     * index-th function is invoked immediately and synchronously.

     * Otherwise the method returns immediately and the function is invoked

     * later.

     *

     * @param index the index of the function as will be passed to

     *   {@link Type#call(java.lang.Object, int, java.lang.Object, java.lang.Object)}

     *   method

     * @param args array of arguments that will be passed as

     *   <code>data</code> argument of the <code>call</code> method.

     * @since 0.7.6

     */

    public void runInBrowser(final int index, final Object... args) {

        context.execute(new Runnable() {

            @Override

            public void run() {

                try {

                    type.call(obj, index, args, null);

                } catch (Exception ex) {

                    ex.printStackTrace();

                }

            }

        });

    }

    /** Initializes the provided collection with a content of the <code>array</code>.

     * The initialization can only be done soon after the the collection

     * is created, otherwise an exception is throw

     *

     * @param to the collection to initialize (assumed to be empty)

     * @param array the array to add to the collection

     * @throws IllegalStateException if the system has already been initialized

     */

    public void initTo(Collection<?> to, Object array) {

        if (ko != null) {

            throw new IllegalStateException();

        }

        if (to instanceof JSONList) {

           ((JSONList)to).init(array);

        } else {

            JSONList.init(to, array);

        }

    }

    /** Takes an object representing JSON result and extract some of its

     * properties. It is assumed that the <code>props</code> and

     * <code>values</code> arrays have the same length.

     *

     * @param json the JSON object (actual type depends on the associated

     *   {@link Technology})

     * @param props list of properties to extract

     * @param values array that will be filled with extracted values

     */

    public void extract(Object json, String[] props, Object[] values) {

        JSON.extract(context, json, props, values);

    }

    /** Converts raw JSON <code>data</code> into a Java {@link Model} class.

     *

     * @param <T> type of the model class

     * @param modelClass the type of the class to create

     * @param data the raw JSON data

     * @return newly created instance of the model class

     */

    public <T> T read(Class<T> modelClass, Object data) {

        return JSON.read(context, modelClass, data);

    }

    /** Initializes asynchronous JSON connection to specified URL. Delegates

     * to {@link #loadJSON(int, java.lang.String, java.lang.String, java.lang.String, java.lang.Object, java.lang.Object...) }

     * with no extra parameters.

     *

     * @param index the callback index to be used when a reply is received

     *   to call {@link Type#onMessage(java.lang.Object, int, int, java.lang.Object)}.

     *

     * @param urlBefore the part of the URL before JSON-P callback parameter

     * @param urlAfter the rest of the URL or <code>null</code> if no JSON-P is used

     * @param method method to use for connection to the server

     * @param data string, number or a {@link Model} generated class to send to

     *    the server when doing a query

     */

    public void loadJSON(final int index,

        String urlBefore, String urlAfter, String method,

        final Object data

    ) {

        loadJSON(index, urlBefore, urlAfter, method, data, new Object[0]);

    }

    /** Initializes asynchronous JSON connection to specified URL. The

     * method returns immediately and later does callback later.

     *

     * @param index the callback index to be used when a reply is received

     *   to call {@link Type#onMessage(java.lang.Object, int, int, java.lang.Object)}.

     *

     * @param urlBefore the part of the URL before JSON-P callback parameter

     * @param urlAfter the rest of the URL or <code>null</code> if no JSON-P is used

     * @param method method to use for connection to the server

     * @param data string, number or a {@link Model} generated class to send to

     *    the server when doing a query

     * @param params extra params to pass back when calling

     *   {@link Type#onMessage(java.lang.Object, int, int, java.lang.Object, java.lang.Object[])}

     * @since 0.8.1

     */

    public void loadJSON(final int index,

        String urlBefore, String urlAfter, String method,

        final Object data, final Object... params

    ) {

        loadJSONWithHeaders(index, null, urlBefore, urlAfter, method, data, params);

    }

    /** Initializes asynchronous JSON connection to specified URL. The

     * method returns immediately and later does callback later.

     *

     * @param index the callback index to be used when a reply is received

     *   to call {@link Type#onMessage(java.lang.Object, int, int, java.lang.Object)}.

     *

     * @param headers headers to use for the request or <code>null</code> to use default ones

     * @param urlBefore the part of the URL before JSON-P callback parameter

     * @param urlAfter the rest of the URL or <code>null</code> if no JSON-P is used

     * @param method method to use for connection to the server

     * @param data string, number or a {@link Model} generated class to send to

     *    the server when doing a query

     * @param params extra params to pass back when calling

     *   {@link Type#onMessage(java.lang.Object, int, int, java.lang.Object, java.lang.Object[])}

     * @since 1.2

     */

    public void loadJSONWithHeaders(final int index,

        String headers,

        String urlBefore, String urlAfter, String method,

        final Object data, final Object... params

    ) {

        class Rcvr extends RcvrJSON {

            @Override

            protected void onMessage(MsgEvnt msg) {

                type.onMessage(obj, index, 1, msg.getValues(), params);

            }

            @Override

            protected void onError(MsgEvnt msg) {

                type.onMessage(obj, index, 2, msg.getException(), params);

            }

        }

        JSONCall call = PropertyBindingAccessor.createCall(

            context, new Rcvr(), headers, urlBefore, urlAfter, method, data

        );

        Transfer t = JSON.findTransfer(context);

        t.loadJSON(call);

    }

    /** Opens new WebSocket connection to the specified URL.

     *

     * @param index the index to use later during callbacks to

     *   {@link Type#onMessage(java.lang.Object, int, int, java.lang.Object)}

     * @param url the <code>ws://</code> or <code>wss://</code> URL to connect to

     * @param data data to send to server (usually <code>null</code>)

     * @return returns a non-null object representing the socket

     *   which can be used when calling {@link #wsSend(java.lang.Object, java.lang.String, java.lang.Object) }

     */

    public Object wsOpen(final int index, String url, Object data) {

        class WSrcvr extends RcvrJSON {

            @Override

            protected void onError(MsgEvnt msg) {

                type.onMessage(obj, index, 2, msg.getException());

            }

            @Override

            protected void onMessage(MsgEvnt msg) {

                type.onMessage(obj, index, 1, msg.getValues());

            }

            @Override

            protected void onClose(MsgEvnt msg) {

                type.onMessage(obj, index, 3, null);

            }

            @Override

            protected void onOpen(MsgEvnt msg) {

                type.onMessage(obj, index, 0, null);

            }

        }

        WS ws = WS.create(JSON.findWSTransfer(context), new WSrcvr());

        ws.send(context, null, url, data);

        return ws;

    }

    /** Sends a message to existing socket.

     *

     * @param webSocket the socket to send message to

     * @param url the <code>ws://</code> or <code>wss://</code> URL to connect to,

     *    preferably the same as the one used when the socket was

     *    {@link #wsOpen(int, java.lang.String, java.lang.Object) opened}

     * @param data the data to send or <code>null</code> if the socket is

     *    supposed to be closed

     */

    public void wsSend(Object webSocket, String url, Object data) {

        ((JSON.WS)webSocket).send(context, null, url, data);

    }

    /** Converts raw data (one of its properties) to string representation.

     *

     * @param data the object

     * @param propName the name of object property or <code>null</code>

     *   if the whole object should be converted

     * @return the string representation of the object or its property

     */

    public String toString(Object data, String propName) {

        return JSON.toString(context, data, propName);

    }

    /** Converts raw data (one of its properties) to a number representation.

     *

     * @param data the object

     * @param propName the name of object property or <code>null</code>

     *   if the whole object should be converted

     * @return the number representation of the object or its property

     */

    public Number toNumber(Object data, String propName) {

        return JSON.toNumber(context, data, propName);

    }

    /** Converts raw JSON data into a {@link Model} class representation.

     *

     * @param <T> type of the model to create

     * @param type class of the model to create

     * @param data raw JSON data (depends on associated {@link Technology})

     * @return new instances of the model class filled with values from the

     *   <code>data</code> object

     */

    public <T> T toModel(Class<T> type, Object data) {

        return JSON.toModel(context, type, data, null);

    }

    /** Creates new JSON like observable list.

     *

     * @param <T> the type of the list elements

     * @param propName name of a property this list is associated with

     * @param onChange index of the property to use when the list is modified

     *   during callback to {@link Type#onChange(java.lang.Object, int)}

     * @param dependingProps the array of {@link ComputedProperty derived properties}

     *   that depend on the value of the list

     * @return new, empty list associated with this proto-object and its model

     */

    public <T> List<T> createList(String propName, int onChange, String... dependingProps) {

        return new JSONList<T>(this, propName, onChange, dependingProps);

    }

    /** Copies content of one collection to another, re-assigning all its

     * elements from their current context to the new <code>ctx</code>.

     *

     * @param <T> type of the collections

     * @param to the target collection to be filled with cloned values

     * @param ctx context for the new collection

     * @param from original collection with its data

     */

    public <T> void cloneList(Collection<T> to, BrwsrCtx ctx, Collection<T> from) {

        Boolean isModel = null;

        for (T t : from) {

            if (isModel == null) {

                isModel = JSON.isModel(t.getClass());

            }

            if (isModel) {

                to.add(JSON.bindTo(t, ctx));

            } else {

                to.add(t);

            }

        }

    }

    //

    // internal state

    //

    final String toStr() {

        return "Proto[" + obj + "]@" + Integer.toHexString(System.identityHashCode(this));

    }

    final Bindings initBindings() {

        if (ko == null) {

            Bindings b = Bindings.apply(context, obj);

            PropertyBinding[] pb = new PropertyBinding[type.propertyNames.length];

            for (int i = 0; i < pb.length; i++) {

                pb[i] = b.registerProperty(

                    type.propertyNames[i], i, obj, type, type.propertyReadOnly[i]

                );

            }

            FunctionBinding[] fb = new FunctionBinding[type.functions.length];

            for (int i = 0; i < fb.length; i++) {

                fb[i] = FunctionBinding.registerFunction(

                    type.functions[i], i, obj, type

                );

            }

            ko = b;

            b.finish(obj, pb, fb);

        }

        return ko;

    }

    final Bindings getBindings() {

        return ko;

    }

    final void onChange(int index) {

        type.onChange(obj, index);

    }

    final Observers observers(boolean create) {

        if (create && observers == null) {

            observers = new Observers();

        }

        return observers;

    }

    /** Functionality used by the code generated by annotation

     * processor for the {@link net.java.html.json.Model} annotation.

     *

     * @param <Model> the generated class

     * @since 0.7

     */

    public static abstract class Type<Model> {

        private final Class<Model> clazz;

        private final String[] propertyNames;

        private final boolean[] propertyReadOnly;

        private final String[] functions;

        /** Constructor for subclasses generated by the annotation processor

         * associated with {@link net.java.html.json.Model} annotation.

         *

         * @param clazz the generated model class

         * @param modelFor the original class annotated by the {@link net.java.html.json.Model} annotation.

         * @param properties number of properties the class has

         * @param functions  number of functions the class has

         */

        protected Type(

            Class<Model> clazz, Class<?> modelFor, int properties, int functions

        ) {

            assert getClass().getName().endsWith("$Html4JavaType");

            try {

                assert clazz == modelFor || getClass().getDeclaringClass() == clazz;

            } catch (SecurityException ex) {

                // OK, no check

            }

            this.clazz = clazz;

            this.propertyNames = new String[properties];

            this.propertyReadOnly = new boolean[properties];

            this.functions = new String[functions];

            JSON.register(clazz, this);

        }

        /** Registers property for the type. It is expected each index

         * is initialized only once.

         *

         * @param name name of the property

         * @param index index of the property

         * @param readOnly is the property read only?

         */

        protected final void registerProperty(String name, int index, boolean readOnly) {

            assert propertyNames[index] == null;

            propertyNames[index] = name;

            propertyReadOnly[index] = readOnly;

        }

        /** Registers function of given name at given index.

         *

         * @param name name of the function

         * @param index name of the type

         */

        protected final void registerFunction(String name, int index) {

            assert functions[index] == null;

            functions[index] = name;

        }

        /** Creates new proto-object for given {@link Model} class bound to

         * provided context.

         *

         * @param obj instance of appropriate {@link Model} class

         * @param context the browser context

         * @return new proto-object that the generated class can use for

         *   communication with the infrastructure

         */

        public Proto createProto(Object obj, BrwsrCtx context) {

            return new Proto(obj, this, context);

        }

        //

        // Implemented by subclasses

        //

        /** Sets value of a {@link #registerProperty(java.lang.String, int, boolean) registered property}

         * to new value.

         *

         * @param model the instance of {@link Model model class}

         * @param index index of the property used during registration

         * @param value the value to set the property to

         */

        protected abstract void setValue(Model model, int index, Object value);

        /** Obtains and returns value of a

         * {@link #registerProperty(java.lang.String, int, boolean) registered property}.

         *

         * @param model the instance of {@link Model model class}

         * @param index index of the property used during registration

         * @return current value of the property

         */

        protected abstract Object getValue(Model model, int index);

        /** Invokes a {@link #registerFunction(java.lang.String, int)} registered function

         * on given object.

         *

         * @param model the instance of {@link Model model class}

         * @param index index of the property used during registration

         * @param data the currently selected object the function is about to operate on

         * @param event the event that triggered the event

         * @throws Exception the method can throw exception which is then logged

         */

        protected abstract void call(Model model, int index, Object data, Object event)

        throws Exception;

        /** Re-binds the model object to new browser context.

         *

         * @param model the instance of {@link Model model class}

         * @param ctx browser context to clone the object to

         * @return new instance of the model suitable for new context

         */

        protected abstract Model cloneTo(Model model, BrwsrCtx ctx);

        /** Reads raw JSON data and converts them to our model class.

         *

         * @param c the browser context to work in

         * @param json raw JSON data to get values from

         * @return new instance of model class filled by the data

         */

        protected abstract Model read(BrwsrCtx c, Object json);

        /** Called when a {@link #registerProperty(java.lang.String, int, boolean) registered property}

         * changes its value.

         *

         * @param model the object that has the property

         * @param index the index of the property during registration

         */

        protected abstract void onChange(Model model, int index);

        /** Finds out if there is an associated proto-object for given

         * object.

         *

         * @param object an object, presumably (but not necessarily) instance of Model class

         * @return associated proto-object or <code>null</code>

         */

        protected abstract Proto protoFor(Object object);

        /** Called to report results of asynchronous over-the-wire

         * communication. Result of calling {@link Proto#wsOpen(int, java.lang.String, java.lang.Object)}

         * or {@link Proto#loadJSON(int, java.lang.String, java.lang.String, java.lang.String, java.lang.Object, java.lang.Object...)}.

         *

         * @param model the instance of the model class

         * @param index index used during initiating the communication (via <code>loadJSON</code> or <code>wsOpen</code> calls)

         * @param type type of the message: 0 - onOpen, 1 - onMessage, 2 - onError, 3 - onClose -

         *   not all messages are applicable to all communication protocols (JSON has only 1 and 2).

         * @param data <code>null</code> or string, number or a {@link Model} class

         *   obtained to the server as a response

         */

        protected void onMessage(Model model, int index, int type, Object data) {

            onMessage(model, index, type, data, new Object[0]);

        }

        /** Called to report results of asynchronous over-the-wire

         * communication. Result of calling {@link Proto#wsOpen(int, java.lang.String, java.lang.Object)}

         * or {@link Proto#loadJSON(int, java.lang.String, java.lang.String, java.lang.String, java.lang.Object, java.lang.Object...)}.

         *

         * @param model the instance of the model class

         * @param index index used during initiating the communication (via <code>loadJSON</code> or <code>wsOpen</code> calls)

         * @param type type of the message: 0 - onOpen, 1 - onMessage, 2 - onError, 3 - onClose -

         *   not all messages are applicable to all communication protocols (JSON has only 1 and 2).

         * @param data <code>null</code> or string, number or a {@link Model} class

         *   obtained to the server as a response

         * @param params extra parameters as passed for example to

         *   {@link Proto#loadJSON(int, java.lang.String, java.lang.String, java.lang.String, java.lang.Object, java.lang.Object...)}

         *   method

         * @since 0.8.1

         */

        protected void onMessage(Model model, int index, int type, Object data, Object[] params) {

            onMessage(model, index, type, data);

        }

        //

        // Various support methods the generated classes use

        //

        /** Converts and array of raw JSON objects into an array of typed

         * Java {@link Model} classes.

         *

         * @param <T> the type of the destination array

         * @param context browser context to use

         * @param src array of raw JSON objects

         * @param destType type of the individual array elements

         * @param dest array to be filled with read type instances

         */

        public <T> void copyJSON(BrwsrCtx context, Object[] src, Class<T> destType, T[] dest) {

            for (int i = 0; i < src.length && i < dest.length; i++) {

                dest[i] = org.netbeans.html.json.impl.JSON.read(context, destType, src[i]);

            }

        }

        /** Compares two objects that can be converted to integers.

         * @param a first value

         * @param b second value

         * @return true if they are the same

         */

        public final boolean isSame(int a, int b) {

            return a == b;

        }

        /** Compares two objects that can be converted to (floating point)

         * numbers.

         * @param a first value

         * @param b second value

         * @return  true if they are the same

         */

        public final boolean isSame(double a, double b) {

            return a == b;

        }

        /** Compares two objects for being the same - e.g. either <code>==</code>

         * or <code>equals</code>.

         * @param a first value

         * @param b second value

         * @return true if they are equals

         */

        public final boolean isSame(Object a, Object b) {

            if (a == b) {

                return true;

            }

            if (a == null || b == null) {

                return false;

            }

            return a.equals(b);

        }

        /** Cumulative hash function. Adds hashcode of the object to the

         * previous value.

         * @param o the object (or <code>null</code>)

         * @param h the previous value of the hash

         * @return new hash - the old one xor the object's one

         */

        public final int hashPlus(Object o, int h) {

            return o == null ? h : h ^ o.hashCode();

        }

        /** Converts an object to its JSON value.

         *

         * @param obj the object to convert

         * @return JSON representation of the object

         */

        public final String toJSON(Object obj) {

            return JSON.toJSON(obj);

        }

        /** Converts the value to string.

         *

         * @param val the value

         * @return the converted value

         */

        public final String stringValue(Object val) {

            return JSON.stringValue(val);

        }

        /** Converts the value to number.

         *

         * @param val the value

         * @return the converted value

         */

        public final Number numberValue(Object val) {

            return JSON.numberValue(val);

        }

        /** Converts the value to character.

         *

         * @param val the value

         * @return the converted value

         */

        public final Character charValue(Object val) {

            return JSON.charValue(val);

        }

        /** Converts the value to boolean.

         *

         * @param val the value

         * @return the converted value

         */

        public final Boolean boolValue(Object val) {

            return JSON.boolValue(val);

        }

        /** Extracts value of specific type from given object.

         *

         * @param <T> the type of object one is interested in

         * @param type the type

         * @param val the object to convert to type

         * @return the converted value

         */

        public final <T> T extractValue(Class<T> type, Object val) {

            if (Number.class.isAssignableFrom(type)) {

                val = numberValue(val);

            }

            if (Boolean.class == type) {

                val = boolValue(val);

            }

            if (String.class == type) {

                val = stringValue(val);

            }

            if (Character.class == type) {

                val = charValue(val);

            }

            if (Integer.class == type) {

                val = val instanceof Number ? ((Number) val).intValue() : 0;

            }

            if (Long.class == type) {

                val = val instanceof Number ? ((Number) val).longValue() : 0;

            }

            if (Short.class == type) {

                val = val instanceof Number ? ((Number) val).shortValue() : 0;

            }

            if (Byte.class == type) {

                val = val instanceof Number ? ((Number) val).byteValue() : 0;

            }

            if (Double.class == type) {

                val = val instanceof Number ? ((Number) val).doubleValue() : Double.NaN;

            }

            if (Float.class == type) {

                val = val instanceof Number ? ((Number) val).floatValue() : Float.NaN;

            }

            if (type.isEnum() && val instanceof String) {

                val = Enum.valueOf(type.asSubclass(Enum.class), (String)val);

            }

            return type.cast(val);

        }

        /** Special dealing with array & {@link List} values. This method

         * takes the provided collection, empties it and fills it again

         * with values extracted from <code>value</code> (which is supposed

         * to be an array).

         *

         * @param <T> the type of list elements

         * @param arr collection to fill with elements in value

         * @param type the type of elements in the collection

         * @param value array of elements to put into the collecition. If

         *   value is not an array it is wrapped into array with only element

         * @since 1.0

         */

        public final <T> void replaceValue(Collection<? super T> arr, Class<T> type, Object value) {

            Object[] newArr;

            if (value instanceof Object[]) {

                newArr = (Object[]) value;

            } else {

                newArr = new Object[] { value };

            }

            List<T> tmp = new ArrayList<T>(newArr.length);

            for (Object e : newArr) {

                tmp.add(extractValue(type, e));

            }

            if (arr instanceof JSONList) {

                JSONList jsList = (JSONList) arr;

                jsList.fastReplace(tmp);

            } else {

                arr.clear();

                arr.addAll(tmp);

            }

        }

    }

}