[Asterisk-java-devel] 2.0 release

[Brett S. <bs...@no...>]

So lets talk about the 2.0 release.

The objective of 2.0 will be to support Asterisk Java 11, 12 and 13 in 
addition to the already supported versions.

At this point I don't see 2.0 supporting ARI, I'm thinking that should 
be a 3.0 target.

I do however want to open up the discussion about improving the 2.0 
interface.

One concern I have with what I'm about to propose is that it has the 
potential to break binary compatibility.

But lets talk anyway.

One of the frustrations I have with asterisk java is that Channels and 
Endpoints are all treated as string.
There are a number of places in the code base that claim something is a 
channel when if fact it isn't.

To solve this problem in our code base we have a event/action 
translation layer which converts Channels and End point strings to 
actual classes of the same name.

Once the conversion is down we have found that it significantly reduces 
the amount of code to handle channels and end points as well as reducing 
the bugs around handling nulls and empty strings.

The second and related issues is that the method of using strings to 
store channels is that it causes problems when rename events occur. Its 
my understanding that in 13 and the new sip libraries that rename events 
go away. That however doesn't help anyone using an earlier version of 
asterisk java and it means that you have to have two different code 
bases to handle the different versions of asterisk.

In our code base along with the above classes for Channels and Endpoints 
we also transparently handle rename events. The Channel object is 
actually a proxy for the actually channel so we can rename the Channel 
under the hood with the code needing to be aware of the change.

So Noojee is willing to donate the code we have to does the above. The 
question is whether it will cause a major breakage of code (uncertain 
although a decent toString method on the classes may make this 
transparent) and whether we should be considering what amounts to a 
fairly major change to the code base.

Here are the interfaces we use:


package au.com.noojeeit.pbx;

import au.com.noojeeit.pbx.asterisk.InvalidChannelName;

/**
  * Provides an abstraction for an channel object which is independent 
of the
  * underlying PBX.
  *
  * @author bsutton
  *
  */
public interface iChannel
{
     /**
      * Compares if two channels are the same logical channel on the pbx.
      *
      * This comparison uses the full unique name of the channel not 
just the
      * abbreviated peer name. e.g. SIP/100-00000100
      *
      * @param rhs
      * @return
      */
     boolean isSame(iChannel rhs);

     boolean isSame(String channelName, String uniqueID);

     /*
      * This comparision uses just the peer name. e.g. SIP/100
      */
     boolean sameEndPoint(iChannel rhs);

     /*
      * This comparision uses just the peer name. e.g. SIP/100
      */
     boolean sameEndPoint(iEndPoint endPoint);

     /**
      * Compares if this channel is the same as the named channel.
      *
      * @param channelName
      * @return
      */
     boolean sameExtenededChannelName(String channelName);

     /**
      * This method does not actually change the state of the channel, 
rather it
      * is intended to be used to record the fact that the state has 
changed.
      *
      * @see public iPBX.iParkCallActivity park(iChannel channel, Direction
      *      direction, boolean parkState) for a method which actually 
parks the
      *      channel.
      */
     void setParked(boolean parked);

     /**
      * This method does not actually change the state of the channel, 
rather it
      * is intended to be used to record the fact that the state has 
changed.
      *
      * @see public iPBX.iMuteCallActivity mute(iChannel channel, Direction
      *      direction, boolean muteState) for a method which actually 
mutes the
      *      channel.
      */
     void setMute(boolean muteState);

     /**
      * Each channel is assigned a unique PBX independent id to help 
track the
      * channels when logging.
      *
      * @return
      */
     long getChannelId();

     /**
      * Returns true if the channel is alive. A channel is considered to 
be alive
      * from the moment it is created until we get a notification that 
it has
      * been hungup.
      *
      * @return
      */
     boolean isLive();

     /**
      * Adds a listener to the channel. The channel will send a hungup
      * notification to the listener when it hungup. A channel must be 
able to
      * support multiple listeners.
      *
      * @param call
      */
     void addListener(iChannelHangupListener listener);

     void removeListener(iChannelHangupListener listener);

     /**
      * Returns true if the given endpont is currently connected to this 
channel.
      *
      * @param extension
      * @return
      */
     boolean isConnectedTo(iEndPoint endPoint);

     /**
      * returns a fully qualifed channel name which includes the tech. e.g.
      * SIP/100-00000342
      *
      * @return
      */
     String getChannelName();

     iEndPoint getEndPoint();

     /**
      * Checks if this channel is currently mute. A channel is mute if 
the party
      * connected to this channel cannot hear any audio.
      *
      * @return
      */
     boolean isMute();

     /**
      * In Asterisk speak, this method returns true if it is a LOCAL/ 
channel Not
      * quite certain how this will map to other pbx's
      *
      * @return
      */
     boolean isLocal();


     /**
      *
      * @return true if the channel is currently parked.
      */
     boolean isParked();

     /**
      * Returns true if the channel has been marked as in a zombie state.
      *
      * @return
      */
     boolean isZombie();


     /**
      *
      * @return true if the channel was originated from the console
      *         (Console/DSP).
      */
     boolean isConsole();

     /**
      * Returns the current callerid for this channel.
      *
      * Note: on some systems this involves a round trip to the pbx.
      *
      * @return
      */
     iCallerID getCallerID();

     /**
      * Called to rename a channel
      *
      * @param newname
      *            the new name of the channel
      * @throws InvalidChannelName
      */
     void rename(String newName) throws InvalidChannelName;

     /**
      * Returns a PBX specific version of the Channel name.
      *
      * @return
      */
     String getExtendedChannelName();

     void notifyHangupListeners();

     boolean canDetectHangup();

     boolean isQuiescent();

     boolean hasCallerID();

}


package au.com.noojeeit.pbx;

import au.com.noojeeit.pbx.asterisk.core.Tech;

/**
  * Provides an abstract interface for entities which can be dialed.
  *
  * This encompasses entities such as: Phone extensions SIPPeers Asterisk
  * extensions External phone numbers
  *
  * @author bsutton
  *
  */
public interface iEndPoint extends Comparable<iEndPoint>
{
     public boolean isSame(iEndPoint rhs);

     public boolean isLocal();

     public boolean isSIP();

     /**
      * Returns the fully qualified name of the EndPoint including the 
tech. e.g.
      * SIP/100
      *
      * @return
      */
     public String getFullyQualifiedName();

     /**
      * Returns the simple name of the EndPoint sans the tech. e.g. 
SIP/100 would
      * be returned as 100.
      *
      * @return
      */
     public String getSimpleName();


     /**
      * Returns the simple name of a SIP EndPoint sans the tech. e.g. 
SIP/100 would
      * be returned as 100.
      * If the endpoint is not actually a SIP end point then this method
      * returns the full end point name.
      *
      *
      * @return
      */
     public String getSIPSimpleName();

     /**
      * Returns true if the tech is not know for this end point.
      *
      * @return
      */
     public boolean isUnknown();

     /**
      * Returns the Tech that is used to reach this endpoint.
      *
      * @return
      */
     public Tech getTech();

     public boolean isEmpty();

     /**
      * Sets the tech on the end point to the specified tech.
      *
      * @param sip
      */
     // public void setTech(Tech tech);

}