ipworks
Class Mcast

java.lang.Object
  |
  +--ipworks.Mcast

public class Mcast

extends java.lang.Object

The MCast bean is used to multicast UDP datagrams to multicast capable hosts in multicast capable subnets. It can act both as a client and a server and communicate with any number of hosts simultaneously, as well as generate and receive broadcast packets.

The MCast bean is very similar to UDPPort, except for some additional properties that provide support for multicast datagrams. To send datagrams to a multicast group, simply assign the address of the group to RemoteHost . To receive datagrams from one or more groups, assign the group addresses to MulticastGroup one by one (after the bean is activated. TimeToLive allows to specify how many subnets a packet should be allowed to receive. ReceiveInterface and SendInterface allow you to select the network interface for multicast operations.

The bean is activated/deactivated through the Active property. This property enables or disables sends or receives. The data can be sent in the same way as UDPPort, by calling the Send method with a Text parameter or via the DataToSend property. The destination is specified using the RemoteHost and RemotePort properties. Inbound data is received through the DataIn event.

Constructor Summary

Mcast()

Method Summary

void	addMcastEventListener(ipworks.McastEventListener l)
java.lang.String	config(java.lang.String configurationString) Sets or retrieves a beanconfiguration setting.
void	doEvents() Processes events from the internal message queue.
java.lang.String	getLocalHost() The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
int	getLocalPort() The UDP port in the local host where MCast binds.
java.lang.String	getMulticastGroup() Multicast group to join or leave.
java.lang.String	getReceiveInterface() The interface to receive multicast packets with.
java.lang.String	getRemoteHost() The address of the remote host (multicast group).
int	getRemotePort() The UDP port in the remote host.
java.lang.String	getSendInterface() The interface to send multicast packets from.
int	getTimeToLive() The maximum number of subnets that a multicast datagram can traverse.
boolean	isAcceptData() Enables or disables data reception (the DataIn event).
boolean	isActive() Enables or disables sending and receiving of data.
boolean	isLoopback() Enables or disables loopback of data sent to the multicast group.
void	removeMcastEventListener(ipworks.McastEventListener l)
void	send(byte[] text) Send data to the remote host.
void	setAcceptData(boolean acceptData) Enables or disables data reception (the DataIn event).
void	setActive(boolean active) Enables or disables sending and receiving of data.
void	setDataToSend(byte[] dataToSend) A string of data to be sent to the remote host.
void	setLocalHost(java.lang.String localHost) The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
void	setLocalPort(int localPort) The UDP port in the local host where MCast binds.
void	setLoopback(boolean loopback) Enables or disables loopback of data sent to the multicast group.
void	setMulticastGroup(java.lang.String multicastGroup) Multicast group to join or leave.
void	setReceiveInterface(java.lang.String receiveInterface) The interface to receive multicast packets with.
void	setRemoteHost(java.lang.String remoteHost) The address of the remote host (multicast group).
void	setRemotePort(int remotePort) The UDP port in the remote host.
void	setSendInterface(java.lang.String sendInterface) The interface to send multicast packets from.
void	setTimeToLive(int timeToLive) The maximum number of subnets that a multicast datagram can traverse.

Methods inherited from class java.lang.Object

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

Constructor Detail

Mcast

public Mcast()

Method Detail

isAcceptData

public boolean isAcceptData()

Enables or disables data reception (the DataIn event).

Setting the property to False, temporarily disables data reception (and the DataIn event). Setting the property to True, reenables data reception.

setAcceptData

public void setAcceptData(boolean acceptData)
                   throws IPWorksException

Enables or disables data reception (the DataIn event).

Setting the property to False, temporarily disables data reception (and the DataIn event). Setting the property to True, reenables data reception.

IPWorksException

isActive

public boolean isActive()

Enables or disables sending and receiving of data.

Setting the Active property to True makes MCast create a communication endpoint (socket) which can be used for sending and receiving UDP datagrams. Setting it to False destroys the socket and disables data communications.

setActive

public void setActive(boolean active)
               throws IPWorksException

Enables or disables sending and receiving of data.

Setting the Active property to True makes MCast create a communication endpoint (socket) which can be used for sending and receiving UDP datagrams. Setting it to False destroys the socket and disables data communications.

IPWorksException

setDataToSend

public void setDataToSend(byte[] dataToSend)
                   throws IPWorksException

A string of data to be sent to the remote host. Write-only property.

Assigning a string to the DataToSend property makes the bean send the string to the remote host. The Send method provides similar functionality.

The TCP/IP subsystem attempts to send the string assigned to DataToSend as a complete message. If socket buffers are full, or the message cannot be delivered for any other reason, an error is fired, and no portion of the message is sent. This is different from TCP where portions of the messages can be sent. The bean sends either a complete message or nothing at all.

If you are sending data to the remote host faster than it can process it, or faster than the network's bandwidth allows, the outgoing queue might fill up. When this happens, DataToSend fails with exception 10035: "[10035] Operation would block" (WSAEWOULDBLOCK). You can check this error, and then try to send the data again. .

IPWorksException

getLocalHost

public java.lang.String getLocalHost()

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the bean initiate connections (or accept in the case of server beans) only through that interface.

If the bean is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.

setLocalHost

public void setLocalHost(java.lang.String localHost)
                  throws IPWorksException

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the bean initiate connections (or accept in the case of server beans) only through that interface.

If the bean is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.

IPWorksException

getLocalPort

public int getLocalPort()

The UDP port in the local host where MCast binds.

The LocalPort property must be set before MCast is activated ( Active is set to True). It instructs the bean to bind to a specific port (or communication endpoint) in the local machine.

Setting it to 0 (default) enables the system to choose a port at random. The chosen port will be shown by the LocalPort property after the connection is established.

LocalPort cannot be changed once the bean is Active . Any attempt to set the LocalPort property when the bean is Active will generate an error.

The LocalPort property is useful when trying to send data to services that require a trusted port in the client side.

setLocalPort

public void setLocalPort(int localPort)
                  throws IPWorksException

The UDP port in the local host where MCast binds.

The LocalPort property must be set before MCast is activated ( Active is set to True). It instructs the bean to bind to a specific port (or communication endpoint) in the local machine.

Setting it to 0 (default) enables the system to choose a port at random. The chosen port will be shown by the LocalPort property after the connection is established.

LocalPort cannot be changed once the bean is Active . Any attempt to set the LocalPort property when the bean is Active will generate an error.

The LocalPort property is useful when trying to send data to services that require a trusted port in the client side.

IPWorksException

isLoopback

public boolean isLoopback()

Enables or disables loopback of data sent to the multicast group.

Setting the property to False disables loopback of data sent through the bean (normally loopback is enabled). This property is directly related to the IP_MULTICAST_LOOP socket option.

setLoopback

public void setLoopback(boolean loopback)
                 throws IPWorksException

Enables or disables loopback of data sent to the multicast group.

Setting the property to False disables loopback of data sent through the bean (normally loopback is enabled). This property is directly related to the IP_MULTICAST_LOOP socket option.

IPWorksException

getMulticastGroup

public java.lang.String getMulticastGroup()

Multicast group to join or leave.

Multicast groups are joined by assigning values to this property after the bean is activated. More than one group may be joined at the same time. To define which interface to use, the ReceiveInterface property is used.

If the first letter of MulticastGroup is "-" or "+" it determines whether the groups should be left or joined respectively. The default operation is join.

To remove the bean from a multicast group once it is joined, simply assign this groupname (address) to MulticastGroup prefixed by a minus sign "-".

Example (Joining/Leaving Groups)

 MCastControl.Active = true
 MCastControl.MulticastGroup = "+231.31.31.31"
 MCastControl.MulticastGroup = "+232.32.32.32"
 
 MCastControl.MulticastGroup = "-232.32.32.32"
 MCastControl.MulticastGroup = "-231.31.31.31" 

setMulticastGroup

public void setMulticastGroup(java.lang.String multicastGroup)
                       throws IPWorksException

Multicast group to join or leave.

Multicast groups are joined by assigning values to this property after the bean is activated. More than one group may be joined at the same time. To define which interface to use, the ReceiveInterface property is used.

If the first letter of MulticastGroup is "-" or "+" it determines whether the groups should be left or joined respectively. The default operation is join.

To remove the bean from a multicast group once it is joined, simply assign this groupname (address) to MulticastGroup prefixed by a minus sign "-".

Example (Joining/Leaving Groups)

 MCastControl.Active = true
 MCastControl.MulticastGroup = "+231.31.31.31"
 MCastControl.MulticastGroup = "+232.32.32.32"
 
 MCastControl.MulticastGroup = "-232.32.32.32"
 MCastControl.MulticastGroup = "-231.31.31.31" 

IPWorksException

getReceiveInterface

public java.lang.String getReceiveInterface()

The interface to receive multicast packets with. If empty, default is used.

This property is useful when there is more than one network interface, and the one used for receiving multicast datagrams is not the default. If you wish to set an interface other than the system default, provide the IP address of the interface to be set.

The ReceiveInterface property is used together with the MulticastGroup property to join one or more multicast groups. The joining is done after the bean is activated by assigning proper values to MulticastGroup .

setReceiveInterface

public void setReceiveInterface(java.lang.String receiveInterface)
                         throws IPWorksException

The interface to receive multicast packets with. If empty, default is used.

This property is useful when there is more than one network interface, and the one used for receiving multicast datagrams is not the default. If you wish to set an interface other than the system default, provide the IP address of the interface to be set.

The ReceiveInterface property is used together with the MulticastGroup property to join one or more multicast groups. The joining is done after the bean is activated by assigning proper values to MulticastGroup .

IPWorksException

getRemoteHost

public java.lang.String getRemoteHost()

The address of the remote host (multicast group).

To send a multicast datagram, specify a RemoteHost value in the range of 224.0.0.0 to 239.255.255.255. These addresses are reserved as multicast addresses by IP.

setRemoteHost

public void setRemoteHost(java.lang.String remoteHost)
                   throws IPWorksException

The address of the remote host (multicast group).

To send a multicast datagram, specify a RemoteHost value in the range of 224.0.0.0 to 239.255.255.255. These addresses are reserved as multicast addresses by IP.

IPWorksException

getRemotePort

public int getRemotePort()

The UDP port in the remote host.

The RemotePort is the UDP port on the RemoteHost to send UDP datagrams to.

A valid port number (a value between 1 and 65535) is required.

setRemotePort

public void setRemotePort(int remotePort)
                   throws IPWorksException

The UDP port in the remote host.

The RemotePort is the UDP port on the RemoteHost to send UDP datagrams to.

A valid port number (a value between 1 and 65535) is required.

IPWorksException

getSendInterface

public java.lang.String getSendInterface()

The interface to send multicast packets from. If empty, default is used.

This property is useful when there is more than one network interface, and the one used for sending multicast datagrams is not the default. If you wish to set an interface other than the system default, provide the IP address of the interface to be set.

setSendInterface

public void setSendInterface(java.lang.String sendInterface)
                      throws IPWorksException

The interface to send multicast packets from. If empty, default is used.

This property is useful when there is more than one network interface, and the one used for sending multicast datagrams is not the default. If you wish to set an interface other than the system default, provide the IP address of the interface to be set.

IPWorksException

getTimeToLive

public int getTimeToLive()

The maximum number of subnets that a multicast datagram can traverse.

The default value for this property is 7. This is an arbitrary value. You need to specify a value suitable for your application.

Multicast datagrams with a TimeToLive of 0 are not transmitted on any subnetwork. Multicast datagrams with a TimeToLive of 1 are delivered only on the local network. Multicast datagrams with a TimeToLive of greater than 1 may be delivered to more than one subnetwork if there are one or more multicast routers attached to the first-hop subnetwork.

A multicast router does not forward multicast datagrams with destination addresses between 224.0.0.0 and 224.0.0.255, inclusive, regardless of their TimeToLive . This particular range of addresses is reserved for the use of routing protocols and other low-level topology discovery or maintenance protocols, such as gateway discovery and group membership reporting.

setTimeToLive

public void setTimeToLive(int timeToLive)
                   throws IPWorksException

The maximum number of subnets that a multicast datagram can traverse.

The default value for this property is 7. This is an arbitrary value. You need to specify a value suitable for your application.

Multicast datagrams with a TimeToLive of 0 are not transmitted on any subnetwork. Multicast datagrams with a TimeToLive of 1 are delivered only on the local network. Multicast datagrams with a TimeToLive of greater than 1 may be delivered to more than one subnetwork if there are one or more multicast routers attached to the first-hop subnetwork.

A multicast router does not forward multicast datagrams with destination addresses between 224.0.0.0 and 224.0.0.255, inclusive, regardless of their TimeToLive . This particular range of addresses is reserved for the use of routing protocols and other low-level topology discovery or maintenance protocols, such as gateway discovery and group membership reporting.

IPWorksException

config

public java.lang.String config(java.lang.String configurationString)
                        throws IPWorksException

Sets or retrieves a beanconfiguration setting.

Config is a generic method available in every bean. It is used to set and retrieveconfiguration settingsfor the bean.

Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the bean, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY , you must call Config("PROPERTY=VALUE") , where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY") . The value will be returned as a string.

IPWorksException

doEvents

public void doEvents()
              throws IPWorksException

Processes events from the internal message queue.

When DoEvents is called, the bean processes any available events. If no events are available, it waits for a preset period of time, and then returns.

IPWorksException

send

public void send(byte[] text)
          throws IPWorksException

Send data to the remote host.

Calling this method is equivalent to setting the DataToSend property to Text .

IPWorksException

addMcastEventListener

public void addMcastEventListener(ipworks.McastEventListener l)
                           throws java.util.TooManyListenersException

java.util.TooManyListenersException

removeMcastEventListener

public void removeMcastEventListener(ipworks.McastEventListener l)