/*
* 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);
}