/*
* Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:
*
*/

package com.nokia.mj.impl.comms;

import com.nokia.mj.impl.rt.support.Jvm;
import com.nokia.mj.impl.utils.Logger;
import com.nokia.mj.impl.comms.exception.CommsException;

/**
 * This is a CommsEndpoint class, it provides implementation for
 * registering listeners and for synchronous message sending.
 * <p>
 * Comms endpoint provides interprocess communication functionality. Comms communication
 * is point-to-point meaning that client endpoint can be connected to a single server at a time.
 * Communication is message based, where users wrap their payload to CommsMessage.
 * Comms endpoints support synchronous and asynchronous message sending.
 * <p>
 * Messages can be sent asynchronously or synchronously. Synchronous message sending blocks until
 * a reply is received or when specified timeout occurs.
 * <p>
 * CommsListener provides a way to receive messages asynchronously. Listeners are registered
 * to endpoint. When message belonging to listener is received, will Comms endpoint make a
 * callback for listener. Application can register as many listeners as need.
 * <p>
 * Example to use CommsEndpoint class:
 * <pre>
 * <code>
 *       CommsEndpoint comms = new CommsEndpoint();
 *       comms.connect(CommsEndpoint.JAVA_CAPTAIN);
 *       comms.registerListener(MODULE_ID, listener);
 *
 *       CommsMessage message = new CommsMessage();
 *
 *       message.setMessageId(MESSAGE_ID);
 *       message.setModuleId(MODULE_ID);
 *
 *       message.write("hello world from java");
 *
 *       comms.send(message);
 *       comms.destroy();
 * </code>
 * </pre>
 */

public final class CommsEndpoint extends CommsEndpointBase
{
    /**
     * 'well-known' server endpoints
     */
    public static final int JAVA_CAPTAIN = 10000;
    public static final int TCK_RUNNER = 10300;
    public static final int JAVA_PREINSTALLER = 10400;
    public static final int JAVA_APPCONVERTER = 10500;
    public static final int JAVA_DEBUGAPI = 10700;

    /**
     * This constant can be used when synchronous sendReceive should not return because of timeout.
     * SendReceive method will return when reply is received or when connection is closed.
     * @see #sendReceive
     */
    public static final int WAIT_FOR_EVER = -1;

    private boolean iReleaseHandle;

    static
    {
        Jvm.loadSystemLibrary("javacomms");
    }

    public CommsEndpoint()
    {
        iHandle = _create();
        iReleaseHandle = true;
    }

    private CommsEndpoint(int aHandle)
    {
        iHandle = aHandle;
        iReleaseHandle = false;
    }

    public static CommsEndpoint find(String aName)
    {
        int handle = _find(aName);
        CommsEndpoint client = null;
        if (handle != 0)
        {
            client = new CommsEndpoint(handle);
        }
        return client;
    }

    public void connect(int aName) throws CommsException
    {
        checkHandle();
        int rc = _connect(iHandle, aName);
        if (rc!=0)
        {
            throw new CommsException("connect failed, address=" + aName);
        }
    }

    public void disconnect() throws CommsException
    {
        checkHandle();
        int rc = _disconnect(iHandle);
        if (rc!=0)
        {
            throw new CommsException("disconnect failed");
        }
    }

    /**
     * Releases native resources.
     * This method must be called when endpoint is no longer needed.
     * After calling this method it's not possible to call other methods.
     */
    public void destroy()
    {
        if (iHandle != 0)
        {
            if (iReleaseHandle)
            {
                _release(iHandle);
            }
            else
            {
                _detach(iHandle);
            }
        }
        iHandle = 0;
    }


    // native methods
    private native int _create();
    private native int _connect(int handle, int name);
    private native int _disconnect(int handle);
    private native static int _find(String name);
}