org.xmlBlaster.client.activex
Class XmlScriptAccess

java.lang.Object
  java.beans.SimpleBeanInfo
      org.xmlBlaster.client.activex.XmlScriptAccess

All Implemented Interfaces:

java.beans.BeanInfo, I_Callback

public class XmlScriptAccess

extends java.beans.SimpleBeanInfo

implements I_Callback

This bean can be exported to a Microsoft dll (ActiveX component) and be accessed by C# or Visual Basic.Net

Here we support XML scripting access as described in the client.script requirement by calling sendRequest() or alternatively you can use the methods like publishStr() or subscribe() directly. The latter methods have the advantage to return a ready parsed object to the ActiveX component, for example Visual Basic can directly call all methods of SubscribeReturnQos which is returned by subscribe().

Compile the ActiveX control with build activex and see Visual Basic and C# samples in directory xmlBlaster/demo/activex.

As events into ActiveX can't have a return value and can't throw an exception back to us we handle it here as a callback, for example Visual Basic needs to call sendUpdateReturn() or sendUpdateException() after processing a message received by update(). Our update thread blocks until one of those two methods is called, however the blocking times out after 10 minutes which is adjustable with the property client/activex/responseWaitTime given in milli seconds.

One instance of this can hold one permanent connection to the xmlBlaster server, multi threaded access is supported.

Author:

Marcel Ruff

See Also:

client.script requirement, ActiveX Bridge Developer Guide

Field Summary

private Global	glob
private XmlScriptInterpreter	interpreter
private static java.util.logging.Logger	log
private static java.lang.String	ME
private java.io.OutputStream	outStream
private java.io.Reader	reader
private long	responseWaitTime
private UpdateListener	updateListener
private XmlBlasterException	updateReturnException
private EDU.oswego.cs.dl.util.concurrent.Latch	updateReturnLatch
private java.lang.String	updateReturnQos

Fields inherited from interface java.beans.BeanInfo

ICON_COLOR_16x16, ICON_COLOR_32x32, ICON_MONO_16x16, ICON_MONO_32x32

Constructor Summary

XmlScriptAccess()
Create a new access bean.

Method Summary

void	addUpdateListener(UpdateListener updateListener) Add a C# / VisualBasic listener over the ActiveX bridge.
ConnectReturnQos	connect(java.lang.String xmlQos) Login to xmlBlaster.
java.util.Properties	createPropertiesInstance() Access a Properties object to be used later for initialize().
SynchronousCache	createSynchronousCache(int size) Setup the cache mode.
boolean	disconnect(java.lang.String xmlQos) Logout from the server, free all server and client side resources.
EraseReturnQos[]	erase(java.lang.String xmlKey, java.lang.String xmlQos)
MsgUnit[]	get(java.lang.String xmlKey, java.lang.String xmlQos) Get synchronous messages.
MsgUnit[]	getCached(java.lang.String xmlKey, java.lang.String xmlQos)
I_CallbackServer	getCbServer() Access the callback server which is currently used in I_XmlBlasterAccess.
Global	getGlobal() Access the handle of this xmlBlaster connection.
java.lang.String	getId()
void	initArgs(java.lang.String[] args) Initialize the environment.
void	initialize(java.util.Properties properties) Initialize the environment.
boolean	isConnected() Has the connect() method successfully passed?
void	leaveServer() Leaves the connection to the server.
static void	main(java.lang.String[] args) For testing: java org.xmlBlaster.client.activex.XmlScriptAccess
protected java.lang.String	notifyUpdateEvent(java.lang.String cbSessionId, UpdateKey key, byte[] content, UpdateQos qos) Fire an event into C# / VisualBasic containing an updated message.
PublishReturnQos	publishBlob(java.lang.String xmlKey, byte[] content, java.lang.String xmlQos) Publish a message.
PublishReturnQos	publishStr(java.lang.String xmlKey, java.lang.String contentStr, java.lang.String xmlQos) Publish a message.
void	refreshSession() If no communication takes place longer the the lifetime of the session we can refresh the session to avoid auto logout
void	removeUpdateListener(UpdateListener updateListener) Remove a C# / VisualBasic listener.
java.lang.String	sendRequest(java.lang.String xmlRequest) Send xml encoded requests to the xmlBlaster server.
void	setUpdateException(java.lang.String errorCode, java.lang.String message) ActiveX code can call this method to return an exception for the current update message
void	setUpdateReturn(java.lang.String updateReturnQos) ActiveX code needs to call this method to set the return value for the current update message.
SubscribeReturnQos	subscribe(java.lang.String xmlKey, java.lang.String xmlQos) Subscribe to messages.
java.lang.String	toXml() Dump state of this client connection handler into an XML ASCII string.
UnSubscribeReturnQos[]	unSubscribe(java.lang.String xmlKey, java.lang.String xmlQos) Cancel subscription.
java.lang.String	update(java.lang.String cbSessionId, UpdateKey updateKey, byte[] content, UpdateQos updateQos) Enforced by I_Callback

Methods inherited from class java.beans.SimpleBeanInfo

getAdditionalBeanInfo, getBeanDescriptor, getDefaultEventIndex, getDefaultPropertyIndex, getEventSetDescriptors, getIcon, getMethodDescriptors, getPropertyDescriptors, loadImage

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ME

private static java.lang.String ME

glob

private final Global glob

log

private static java.util.logging.Logger log

interpreter

private XmlScriptInterpreter interpreter

reader

private java.io.Reader reader

outStream

private java.io.OutputStream outStream

updateListener

private UpdateListener updateListener

updateReturnLatch

private EDU.oswego.cs.dl.util.concurrent.Latch updateReturnLatch

updateReturnQos

private java.lang.String updateReturnQos

updateReturnException

private XmlBlasterException updateReturnException

responseWaitTime

private long responseWaitTime

Constructor Detail

XmlScriptAccess

public XmlScriptAccess()

Create a new access bean. We read a xmlBlaster.properties file if one is found

Method Detail

addUpdateListener

public void addUpdateListener(UpdateListener updateListener)

Add a C# / VisualBasic listener over the ActiveX bridge. This method is called automatically when activating the bridge

removeUpdateListener

public void removeUpdateListener(UpdateListener updateListener)

Remove a C# / VisualBasic listener. This method is called automatically when deactivating the bridge

notifyUpdateEvent

protected java.lang.String notifyUpdateEvent(java.lang.String cbSessionId,
                                             UpdateKey key,
                                             byte[] content,
                                             UpdateQos qos)
                                      throws XmlBlasterException

Fire an event into C# / VisualBasic containing an updated message.
Note: The ActiveX event can't convey a return value or an exception back to us. There for we block the thread and wait until the activeX component has delivered us a return value or an exception by calling setUpdateReturn() or setUpdateException()

Throws:

XmlBlasterException

setUpdateReturn

public void setUpdateReturn(java.lang.String updateReturnQos)

ActiveX code needs to call this method to set the return value for the current update message. Alternatively you can call setUpdateException() to pass back an exception.
Note: You have to call setUpdateReturn() OR setUpdateException() for each update message to release the blocking thread!

Parameters:

updateReturnQos - for example ""

See Also:

The interface.update requirement

setUpdateException

public void setUpdateException(java.lang.String errorCode,
                               java.lang.String message)

ActiveX code can call this method to return an exception for the current update message

Parameters:

errorCode - Only known ErrorCode strings of type "user.*" are allowed

See Also:

ErrorCode

createPropertiesInstance

public java.util.Properties createPropertiesInstance()

Access a Properties object to be used later for initialize().

Returns:

We create a new instance for you

initialize

public void initialize(java.util.Properties properties)

Initialize the environment.

initArgs

public void initArgs(java.lang.String[] args)

Initialize the environment. If you use the initialize(Properties) variant or this method makes no difference.

Parameters:

args - Command line arguments for example { "-protocol", SOCKET, "-logging", "FINE" }

getGlobal

public Global getGlobal()

Access the handle of this xmlBlaster connection.

sendRequest

public java.lang.String sendRequest(java.lang.String xmlRequest)

Send xml encoded requests to the xmlBlaster server.

Throws:

All - caught exceptions are thrown as RuntimeException

See Also:

client.script requirement

createSynchronousCache

public SynchronousCache createSynchronousCache(int size)

Setup the cache mode.

See Also:

I_XmlBlasterAccess.createSynchronousCache(int), client.cache requirement

connect

public ConnectReturnQos connect(java.lang.String xmlQos)
                         throws XmlBlasterException

Login to xmlBlaster.

Throws:

XmlBlasterException

See Also:

I_XmlBlasterAccess.connect(ConnectQos, org.xmlBlaster.client.I_Callback), interface.connect requirement

leaveServer

public void leaveServer()

Leaves the connection to the server. The server side resources are not freed if the client has connected fail save and messages are queued until we login again with the same name and publicSessionId

See Also:

I_XmlBlasterAccess.leaveServer(java.util.Map)

isConnected

public boolean isConnected()

Has the connect() method successfully passed?

See Also:

I_XmlBlasterAccess.isConnected()

refreshSession

public void refreshSession()
                    throws XmlBlasterException

If no communication takes place longer the the lifetime of the session we can refresh the session to avoid auto logout

Throws:

XmlBlasterException

See Also:

I_XmlBlasterAccess.refreshSession()

getCbServer

public I_CallbackServer getCbServer()

Access the callback server which is currently used in I_XmlBlasterAccess.

See Also:

I_XmlBlasterAccess.getCbServer()

getId

public java.lang.String getId()

See Also:

I_XmlBlasterAccess.getId()

disconnect

public boolean disconnect(java.lang.String xmlQos)
                   throws XmlBlasterException

Logout from the server, free all server and client side resources.

Returns:

false if connect() wasn't called before or if you call disconnect() multiple times

Throws:

XmlBlasterException

See Also:

I_XmlBlasterAccess.disconnect(DisconnectQos), interface.disconnect requirement

subscribe

public SubscribeReturnQos subscribe(java.lang.String xmlKey,
                                    java.lang.String xmlQos)
                             throws XmlBlasterException

Subscribe to messages.

Parameters:

xmlKey - Which message topics to retrieve

xmlQos - Control the behavior and further filter messages with mime based filter plugins

Throws:

XmlBlasterException - like ErrorCode.USER_NOT_CONNECTED and others

See Also:

I_XmlBlasterAccess.subscribe(SubscribeKey, SubscribeQos, I_Callback)

unSubscribe

public UnSubscribeReturnQos[] unSubscribe(java.lang.String xmlKey,
                                          java.lang.String xmlQos)
                                   throws XmlBlasterException

Cancel subscription.

Throws:

XmlBlasterException

See Also:

I_XmlBlasterAccess.unSubscribe(UnSubscribeKey, UnSubscribeQos), interface.unSubscribe requirement

get

public MsgUnit[] get(java.lang.String xmlKey,
                     java.lang.String xmlQos)
              throws XmlBlasterException

Get synchronous messages.

Parameters:

xmlKey - Which message topics to retrieve

xmlQos - Control the behavior and further filter messages with mime based filter plugins

Throws:

XmlBlasterException - like ErrorCode.USER_NOT_CONNECTED and others

See Also:

interface.get requirement, I_XmlBlasterAccess.get(GetKey, GetQos)

getCached

public MsgUnit[] getCached(java.lang.String xmlKey,
                           java.lang.String xmlQos)
                    throws XmlBlasterException

Throws:

XmlBlasterException

See Also:

I_XmlBlasterAccess.getCached(GetKey, GetQos)

publishStr

public PublishReturnQos publishStr(java.lang.String xmlKey,
                                   java.lang.String contentStr,
                                   java.lang.String xmlQos)
                            throws XmlBlasterException

Publish a message.

Parameters:

xmlKey - The message topic

contentStr - The payload as a string

xmlQos - Control the behavior

Throws:

XmlBlasterException - like ErrorCode.USER_NOT_CONNECTED and others

See Also:

interface.publish requirement, I_XmlBlasterAccess.publish(org.xmlBlaster.util.MsgUnit)

publishBlob

public PublishReturnQos publishBlob(java.lang.String xmlKey,
                                    byte[] content,
                                    java.lang.String xmlQos)
                             throws XmlBlasterException

Publish a message.

Parameters:

xmlKey - The message topic

content - The payload as binary blob

xmlQos - Control the behavior

Throws:

XmlBlasterException - like ErrorCode.USER_NOT_CONNECTED and others

See Also:

interface.publish requirement, I_XmlBlasterAccess.publish(org.xmlBlaster.util.MsgUnit)

erase

public EraseReturnQos[] erase(java.lang.String xmlKey,
                              java.lang.String xmlQos)
                       throws XmlBlasterException

Throws:

XmlBlasterException

See Also:

interface.erase requirement

update

public java.lang.String update(java.lang.String cbSessionId,
                               UpdateKey updateKey,
                               byte[] content,
                               UpdateQos updateQos)
                        throws XmlBlasterException

Enforced by I_Callback

Specified by:

update in interface I_Callback

Parameters:

cbSessionId - The session ID specified by the client which registered the callback. You can specify a cbSessionId during connection (with ConnectQos) and this is bounced back here so you can authenticate the message.

updateKey - The arrived key containing the topic name

content - The arrived message content. This is your payload.

Throws:

XmlBlasterException

See Also:

I_XmlBlasterAccess

toXml

public java.lang.String toXml()

Dump state of this client connection handler into an XML ASCII string.

Returns:

internal state

main

public static void main(java.lang.String[] args)

For testing: java org.xmlBlaster.client.activex.XmlScriptAccess