API_Changes.txt

API changes in 3.0.0
====================

- Old and deprecated system properties such as bind.address (instead of jgroups.bind_addr) have been removed

- Removed package org.jgroups.persistence and changed dependent demos accordingly (e.g. ReplicatedHashMap)

- Removed all options except for Channel.LOCAL
- Removed JChannel.getOpt()/setOpt()
- Discarding of own messages can now be set via setDiscardOwnMessages(true)

- Removed package org.jgroups.mux (e.g. Multiplexer and MuxChannel). Use a shared transport instead. If you have to,
  use classes from package org.jgroups.blocks.mux (only if you're an expert though !)

- Removed (J)ChannelFactory. Inject the channel yourself, e.g. through CDI

- Removed JChannel.receive(). Use a Receiver or ReceiverAdapter and JChannel.setReceiver(Receiver) to switch from a
  pull based approach of receiving messages to a push-based approach

- Removed JChannel.receive(), peek(), shutdown(), open(), returnState(), getAllStates(), blockOK()

- Removed DistributedQueue

- Removed PullPushAdapter. Use a Receiver to get callbacks on messages, views etc

- Removed DistributedLockManager. Use LockService as replacement

- Removed NotificationBus. Use a normal JChannel as replacement

- Removed deprecated methods in MessageDispatcher and RpcDispatcher

- Removed JChannel.getLocalAddress(). Use JChannel.getAddress() instead

- Removed deprecated methods and classes

- Streamable: DataInputStream --> DataInput, DataOutputStream --> DataOutput

- RpcDispatcher: merged Marshaller and Marshaller2 into Marshaller interface

- Removed partial state transfer (nobody ever used it !)

- Removed ExtendedXXXAdapters: there is only Receiver, ReceiverAdapter, MessageListener and MembershipListener
- Moved ExtendedMembershipListener.unblock() into MembershipListener, removed ExtendedMembershipListener

- Changed Request.GET_ALL/GET_FIRST/GET_NONE etc from an int to ResponseMode.GET_ALL etc

- Removed ProtocolTester (use SHARED_LOOPBACK instead)

- Removed Address.isMulticastAddress(): a null address is a multicast address

- Rsp, RspList, RpcDispatcher.callRemoteMethodsXXX() and MessageDispatcher.cast/sendXXX() methods now use
  generics, so the code below:

  RspList rsps=disp.callRemoteMethods(null, call, new RequestOptions(ResponseMode.GET_ALL, 5000));
  for(Map.Entry<Address,Rsp> rsp: rsps.entrySet())
      System.out.println(rsp.getKey() + ": " + rsp.getValue().getValue());

  has to be changed to:

  RspList<Date> rsps=disp.callRemoteMethods(null, call, new RequestOptions(ResponseMode.GET_ALL, 5000));
  for(Map.Entry<Address,Rsp<Date>> rsp: rsps.entrySet())
      System.out.println(rsp.getKey() + ": " + rsp.getValue().getValue());

- RpcDispatcher.callRemoteMethod() now throws an exception if the target method threw an exception

- RpcDispatcher.callRemoteMethods() return a RspList. If a member P threw an exception, then the Rsp for
  P will have it in the field 'exception'. The 'result' field is *not* used for exceptions any longer !

  An example to check for exceptions is:


  Multicast:

  RspList<Long> rsps=dispatcher.callRemoteMethods(null, "foo", null, null, new RequestOptions(...));
  for(Rsp<Long> rsp: rsps.values) {
     if(rsp.getException() != null) {
         // we have an exception
     }
     else {
         Long val=rsp.getValue();
         // do something with the value
     }
  }

  Unicast:

  try {
     Rsp<Long> rsp=disp.callRemoteMethod(target, "foo", null, null, new RequestOptions(...));
     Long val=rsp.getValue();
     // do something with the return value
  }
  catch(Throwable t) {
     // "foo" threw an exception
  }

- ChannelNotConnectedException and ChannelCloseException have been replaced by the superclass ChannelException. This way,
  new exceptions can be thrown (and documented in the javadoc) without having to change the signature in the future.
  These changes affect mainly JChannel

- ChannelException (and subclasses) has been replaced by Exception in all signatures

- State transfer API changes:
  ---------------------------
  - Removed byte[] getState() and void setState(byte[] data) callbacks in MessageListener and Receiver. Use the callbacks
    which use input and output streams instead