Package kr.ac.konkuk.ccslab.cm.stub

Class CMStub

java.lang.Object
kr.ac.konkuk.ccslab.cm.stub.CMStub
Direct Known Subclasses:
CMClientStub, CMServerStub
public class CMStub extends Object
This class provides CM APIs of the common communication services that can be called by both the server and the client applications. This class is the super class of the CMClientStub and the CMServerStub classes. Application developers should generate an instance of the two sub-classes instead of the CMStub class.
See Also:

  • Field Details

    • m_cmInfo

      protected CMInfo m_cmInfo

  • Constructor Details

    • CMStub

      public CMStub()
      Creates an instance of the CMStub class.

      This method is called first when the sub-classes of the CMStub class call the default constructor.

  • Method Details

    • init

      public boolean init()

    • terminateCM

      public void terminateCM()
      Terminates CM.

      This method is called first when the sub-classes of the CMStub class call the overridden methods. All the termination procedure is processed by this method.

    • getCMInfo

      public CMInfo getCMInfo()
      Returns a reference to the CMInfo object that the CMStub object has created.

      The CMInfo object includes all kinds of state information on the current CM.

      Returns:
      a reference to the CMInfo object.
      See Also:

    • findServiceManager

      public <T extends CMServiceManager> T findServiceManager(Class<T> type)
      Returns a CMServiceManager reference with the given type.
      Parameters:
      type - - the class type of CMServiceManager.

      Currently available class types:
      CMMqttManager.class, CMFileSyncManager.class

      The other CM service managers such as CMFileTransferManager, CMSNSManager, CMDBManager and so on will be available. Now, those services are partly available only through the CM stub modules.

      Returns:
      the reference of type T that is a subclass of CMServiceManager if found; null otherwise.

    • setAppEventHandler

      public void setAppEventHandler(CMAppEventHandler handler)
      Registers the event handler of the application.

      An event handler has a role of receiving a CM event whenever it is received. A developer can define an event handler class which includes application codes so that the application can do any task when a CM event is received. The event handler class must implement the CMAppEventHandler interface which defines an event processing method, CMAppEventHandler.processEvent(CMEvent).

      Parameters:
      handler - - the event handler of the application.

    • getAppEventHandler

      public CMAppEventHandler getAppEventHandler()
      Returns the registered event handler of the application.
      Returns:
      the registered event handler of the application.

    • getMyself

      public CMUser getMyself()
      Returns the current client or server information.

      The CMUser class includes the user information such as the name, the host address, the UDP port number, the current session and group names, and so on.

      Returns:
      the current client or the current server information.

    • getDefaultServerName

      public String getDefaultServerName()
      Returns the default server name.
      Returns:
      the default server name.

    • replyEvent

      public boolean replyEvent(CMEvent event, int nReturnCode)
      Replies a request from a remote CM node.

      Some CM events require that a requested application instead of CM needs to determine an answer. In this case, the application can call this method to reply the request with its answer.
      Currently, following CM events can be used to ask an application its answer.

      Parameters:
      event - - the request event
      nReturnCode - - the reply to the request.
      1 : accepts the request.
      0 : rejects the request.
      Returns:
      true if the reply is successfully sent to the requester; false otherwise.

    • addNonBlockDatagramChannel

      public DatagramChannel addNonBlockDatagramChannel(int nChPort)
      Adds a non-blocking datagram (UDP) channel to this CM node.

      A developer must note that the given port number is unique and different from that of the default channel in the configuration file. A UDP channel is identified by the port number as an index.

      Parameters:
      nChPort - - the port number for the new datagram (UDP) channel
      Returns:
      a reference to the datagram channel if it is successfully created, or null otherwise.
      See Also:

    • removeNonBlockDatagramChannel

      public boolean removeNonBlockDatagramChannel(int nChPort)
      Removes a non-blocking datagram (UDP) channel from this CM node.

      Like the stream (TCP) channel case, a developer should be careful not to remove the default channel.

      Parameters:
      nChPort - - the port number of the channel to be removed
      Returns:
      true if the channel is successfully removed, or false otherwise.
      See Also:

    • addBlockDatagramChannel

      public DatagramChannel addBlockDatagramChannel(int nChPort)
      Adds a blocking datagram (UDP) channel to this CM node.

      A UDP channel is identified by the port number as an index.

      Parameters:
      nChPort - - the port number for the new datagram (UDP) channel
      Returns:
      a reference to the datagram channel if it is successfully created, or null otherwise.
      See Also:

    • removeBlockDatagramChannel

      public boolean removeBlockDatagramChannel(int nChPort)
      Removes a blocking datagram (UDP) channel from this CM node.

      Like the stream (TCP) channel case, a developer should be careful not to remove the default channel.

      Parameters:
      nChPort - - the port number of the channel to be removed
      Returns:
      true if the channel is successfully removed, or false otherwise.
      See Also:

    • getBlockDatagramChannel

      public DatagramChannel getBlockDatagramChannel(int nChPort)
      Returns a blocking datagram (UDP) channel.
      Parameters:
      nChPort - - the channel port number.
      Returns:
      the blocking datagram channel, or null if the channel is not found.

    • addMulticastChannel

      public boolean addMulticastChannel(String strSession, String strGroup, String strChAddress, int nChPort)
      Adds an additional multicast channel to this CM node.

      The first and second parameters specify a session and group to which a new channel is assigned, because a multicast channel is always mapped to a specific group in a session. The third and fourth parameters are the multicast address and the port number of the new channel. A developer must note that the given address and the port number are unique and different from that of the default channel in a corresponding session configuration file. A multicast channel is identified by the four-tuple: a session name, a group name, a multicast address, and a port number.

      Parameters:
      strSession - - the session name which the new channel belongs to
      strGroup - - the group name which the new channel belongs to
      strChAddress - - the multicast address
      nChPort - - the port number
      Returns:
      true if the channel is successfully open, or false otherwise.
      See Also:

    • removeAdditionalMulticastChannel

      public boolean removeAdditionalMulticastChannel(String strSession, String strGroup, String strChAddress, int nChPort)
      Removes an additional multicast channel from this CM node.

      Like the other additional channel cases, a developer should be careful not to remove the default channel.

      Parameters:
      strSession - - the session name which the target channel belongs to
      strGroup - - the group name which the target channel belongs to
      strChAddress - - the multicast address
      nChPort - - the port number
      Returns:
      true if the channel is successfully removed, or false otherwise.
      See Also:

    • send

      public boolean send(CMEvent cme, String strTarget)
      Sends a CM event to a single node.

      This method is the same as calling send(cme, strTarget, CMInfo.CM_STREAM, 0, false) of the send(CMEvent, String, int, int, boolean) method.

      Parameters:
      cme - - the CM event
      strTarget - - the receiver name.
      The receiver can be either the server or the client. In the CM network, all the participating nodes (servers and clients) have a string name that can be the value of this parameter. For example, the name of the default server is "SERVER".
      Returns:
      true if the event is successfully sent; false otherwise.
      See Also:

    • send

      public boolean send(CMEvent cme, String strTarget, int opt)
      Sends a CM event to a single node.

      This method is the same as calling send(cme, strTarget, opt, 0, false) of the send(CMEvent, String, int, int, boolean) method.

      Parameters:
      cme - - the CM event
      strTarget - - the receiver name.
      The receiver can be either the server or the client. In the CM network, all the participating nodes (servers and clients) have a string name that can be the value of this parameter. For example, the name of the default server is "SERVER".
      opt - - the reliability option.
      If opt is CMInfo.CM_STREAM (or 0), CM uses TCP socket channel to send the event. If opt is CMInfo.CM_DATAGRAM (or 1), CM uses UDP datagram socket channel.
      Returns:
      true if the event is successfully sent; false otherwise.
      See Also:

    • send

      public boolean send(CMEvent cme, String strTarget, int opt, int nChNum)
      Sends a CM event to a single node.

      This method is the same as calling send(cme, strTarget, opt, nChNum, false) of the send(CMEvent, String, int, int, boolean) method.

      Parameters:
      cme - - the CM event
      strTarget - - the receiver name.
      The receiver can be either the server or the client. In the CM network, all the participating nodes (servers and clients) have a string name that can be the value of this parameter. For example, the name of the default server is "SERVER".
      opt - - the reliability option.
      If opt is CMInfo.CM_STREAM (or 0), CM uses TCP socket channel to send the event. If opt is CMInfo.CM_DATAGRAM (or 1), CM uses UDP datagram socket channel.
      nChNum - - the channel key.
      If the application adds additional TCP or UDP channels, they are identified by the channel key. The key of the TCP channel should be greater than 1 (0 for the default channel), and the key of the UDP channel is the locally bound port number.
      Returns:
      true if the event is successfully sent; false otherwise.
      See Also:

    • send

      public boolean send(CMEvent cme, String strTarget, int opt, int nChNum, boolean isBlock)
      Sends a CM event to a single node.

      This method and the other shortened forms (send(CMEvent, String), send(CMEvent, String, int), and send(CMEvent, String, int, int)) use the default server if the receiver is a client, because they assume that the receiver belongs to the default server. (If the receiver is a server, these send methods can be called without a problem.) If the client wants to send the event to a client that belongs to another server, the client should call the send(CMEvent, String, String, int, int) method. (CM applications can add multiple servers in addition to the default server.)

      Parameters:
      cme - - the CM event
      strTarget - - the receiver name.
      The receiver can be either the server or the client. In the CM network, all the participating nodes (servers and clients) have a string name that can be the value of this parameter. For example, the name of the default server is "SERVER".
      opt - - the reliability option.
      If opt is CMInfo.CM_STREAM (or 0), CM uses TCP socket channel to send the event. If opt is CMInfo.CM_DATAGRAM (or 1), CM uses UDP datagram socket channel.
      nChNum - - the channel key.
      If the application adds additional TCP or UDP channels, they are identified by the channel key. The key of the TCP channel should be greater than 1 (0 for the default channel), and the key of the UDP channel is the locally bound port number.
      isBlock - - the blocking option.
      If isBlock is true, this method uses a blocking channel to send the event. If isBlock is false, this method uses a nonblocking channel to send the event. The CM uses nonblocking channels by default, but the application can also add blocking channels if required.
      Returns:
      true if the event is successfully sent; false otherwise.
      See Also:

    • send

      public boolean send(CMEvent cme, String strTarget, int opt, int nSendPort, int nRecvPort, boolean isBlock)
      Sends a CM event to a single node.

      This method can be called only in the following conditions. First, this method uses only the datagram (udp) channel. Therefore, the opt parameter must be always set to CMInfo.CM_DATAGRAM (or 1). Second, this method can send an event to a CM node of which a target port number (that is not the default port number) is known by the sender. Unlike the other send() methods, this method cannot use the internal forwarding scheme of CM.

      Parameters:
      cme - - the CM event
      strTarget - - the receiver name.
      The receiver can be either the server or the client. In the CM network, all the participating nodes (servers and clients) have a string name that can be the value of this parameter. For example, the name of the default server is "SERVER".
      opt - - the reliability option.
      The opt value of this method must be CMInfo.CM_DATAGRAM (or 1), because this method must be called only with the UDP datagram socket channel.
      nSendPort - - the datagram channel key.
      If the application adds additional UDP channels, they are identified by the channel key. The key of the UDP channel is the locally bound port number.
      nRecvPort - - the receiver port number.
      If nRecvPort is 0, then CM uses the default UDP port of the receiver.
      isBlock - - the blocking option.
      If isBlock is true, this method uses a blocking channel to send the event. If isBlock is false, this method uses a nonblocking channel to send the event. The CM uses nonblocking channels by default, but the application can also add blocking channels if required.
      Returns:
      true if the event is successfully sent; false otherwise.
      See Also:

    • receive

      public CMEvent receive(SocketChannel sc)
      Receives a CM event using a blocking socket channel.

      An application can call this method when it needs to synchronously receive a CM event explicitly with a blocking socket channel. When an application calls the receive method, the application blocks its execution until it receives a CM event through the channel parameter. When an event is received, the method returns the event and the application resumes its execution.
      Only a client can add a blocking socket channel with CMClientStub.addBlockSocketChannel(int, String) method. Furthermore, an application can retrieve its blocking socket channels with CMClientStub.getBlockSocketChannel(int, String) method.

      Parameters:
      sc - - the blocking socket channel through which the caller receives an event.
      Returns:
      a CM event if this method successfully receives, or null otherwise.
      See Also:

    • receive

      public CMEvent receive(DatagramChannel dc)
      Receives a CM event using a blocking datagram channel.

      An application can call this method when it needs to synchronously receive a CM event explicitly with a blocking datagram channel. When an application calls the receive method, the application blocks its execution until it receives a CM event through the channel parameter. When an event is received, the method returns the event and the application resumes its execution.
      The application (server or client) can add a blocking datagram channel with addBlockDatagramChannel(int) method. Furthermore, an application can retrieve its blocking datagram channels with getBlockDatagramChannel(int) method.

      Parameters:
      dc - - the datagram channel through which the caller receives an event.
      Returns:
      a CM event if this method successfully receives, or null otherwise.
      See Also:

    • sendrecv

      public CMEvent sendrecv(CMEvent cme, String strReceiver, int nWaitEventType, int nWaitEventID, int nTimeout)
      Sends a CM event and receive a reply event.

      This method is used when a sender node needs to synchronously communicates with a receiver through the default non-blocking communication channel. Two CM nodes conduct the synchronous communication as follows:

      1. A sender node sends an event to a receiver.
      2. The sender waits until the receiver sends a reply event.
      3. The sender receives the reply event.

      In the step 2, the application main thread suspends its execution after it calls this method. However, the sender still can receive events because CM consists of multiple threads, and the other threads can deal with the reception and process of events.

      Parameters:
      cme - - the event to be sent
      strReceiver - - the target name
      The target node can be a server or a client. If the target is a client, the event and its reply event are delivered through the default server.
      nWaitEventType - - the waited event type of the reply event from 'strReceiver'
      nWaitEventID - - the waited event ID of the reply event from 'strReceiver'
      nTimeout - - the maximum time to wait in milliseconds.
      If nTimeout is greater than 0, the main thread is suspended until the timeout time elapses.
      If nTimeout is 0, the main thread is suspended until the reply event arrives without the timeout.
      Returns:
      a reply CM event if it is successfully received, or null otherwise.
      See Also:

    • cast

      public boolean cast(CMEvent cme, String sessionName, String groupName)
      Sends a CM event to a node group.

      This method is the same as calling cast(cme, sessionName, groupName, CMInfo.CM_STREAM, 0) of the cast(CMEvent, String, String, int, int) method.

      Parameters:
      cme - - the CM event
      sessionName - - the target session name
      If sessionName is null (not specified), the event is sent to all sessions. In this case, the groupName parameter must be also null.
      groupName - - the target group name
      If groupName is null (not specified), the event is sent to all groups in a session.
      Returns:
      true if the event is successfully sent; false otherwise.
      See Also:

    • cast

      public boolean cast(CMEvent cme, String sessionName, String groupName, int opt)
      Sends a CM event to a node group.

      This method is the same as calling cast(cme, sessionName, groupName, opt, 0) of the cast(CMEvent, String, String, int, int) method.

      Parameters:
      cme - - the CM event
      sessionName - - the target session name
      If sessionName is null (not specified), the event is sent to all sessions. In this case, the groupName parameter must be also null.
      groupName - - the target group name
      If groupName is null (not specified), the event is sent to all groups in a session.
      opt - - the reliability option.
      If opt is CMInfo.CM_STREAM (or 0), CM uses TCP socket channel to send the event. If opt is CMInfo.CM_DATAGRAM (or 1), CM uses UDP datagram socket channel.
      Returns:
      true if the event is successfully sent; false otherwise.
      See Also:

    • cast

      public boolean cast(CMEvent cme, String sessionName, String groupName, int opt, int nChNum)
      Sends a CM event to a node group.

      The cast method sends a CM event to a receivers group using multiple one-to-one transmission. The range of receivers can be set with a session and a group. That is, this method sends an event to a specific session members or group members. With the different combination of the sessionName and groupName parameters, the range of receivers is different as described below.

      Receiver ranges of the chat() method
      sessionNamegroupNamereceiver range
      not nullnot nullall members of a group (groupName) in a session (sessionName)
      not nullnullall members of all groups in a session (sessionName)
      nullnullall members of all groups in all sessions (= all login users in the default server)
      Parameters:
      cme - - the CM event
      sessionName - - the target session name
      If sessionName is null (not specified), the event is sent to all sessions. In this case, the groupName parameter must be also null.
      groupName - - the target group name
      If groupName is null (not specified), the event is sent to all groups in a session.
      opt - - the reliability option.
      If opt is CMInfo.CM_STREAM (or 0), CM uses TCP socket channel to send the event. If opt is CMInfo.CM_DATAGRAM (or 1), CM uses UDP datagram socket channel.
      nChNum - - the channel key.
      If the application adds additional TCP or UDP channels, they are identified by the channel key. The key of the TCP channel should be greater than 1 (0 for the default channel), and the key of the UDP channel is the locally bound port number.
      Returns:
      true if the event is successfully sent; false otherwise.
      See Also:

    • castrecv

      public CMEvent[] castrecv(CMEvent event, String strSessionName, String strGroupName, int nWaitedEventType, int nWaitedEventID, int nMinNumWaitedEvents, int nTimeout)
      Sends a CM event and receive multiple reply events.

      This method is used when a sender node needs to synchronously communicates with multiple receivers (CM group members, session members, or all login users) through the default non-blocking communication channel. A sender node and multiple receiver nodes conduct the synchronous communication as follows:

      1. A sender node sends an event to receivers that are specified by a session name and a group name.
      2. The sender waits until at least the given minimum number of receivers send reply events.
      3. The sender receives an array of received reply events.

      In the step 2, the application main thread suspends its execution after it calls this method. However, the sender still can receive events because CM consists of multiple threads, and the other threads can deal with the reception and process of events.

      Parameters:
      event - - the event to be sent
      strSessionName - - the target session name
      If this parameter is null, it implies all sessions. If 'strGroupName' is not null, this parameter must not be null, either.
      strGroupName - - the target group name
      If this parameter is null, it implies all groups.
      nWaitedEventType - - the waited event type of the reply event
      nWaitedEventID - - the waited event ID of the reply event
      nMinNumWaitedEvents - - the minimum number of waited events
      The sender waits until it receives at least 'nMinNumWaitedEvents' events.
      nTimeout - - the maximum time to wait in milliseconds.
      If nTimeout is greater than 0, the main thread is suspended until the timeout time elapses.
      If nTimeout is 0, the main thread is suspended until the all reply events arrives without the timeout.
      Returns:
      an array of reply CM events if the minimum number (nMinNumWaitedEvents) of reply events are successfully received, or null otherwise.
      The size of the array can be greater than 'nMinNumWaitedEvents'.
      See Also:

    • multicast

      public boolean multicast(CMEvent cme, String sessionName, String groupName)
      Sends a CM event to a node group via multicast.

      If a CM server application sets the communication architecture as the CM_PS in the server configuration file, it creates a multicast channel assigned to each group. In this case, the server and client applications can send an event using a multicast channel.
      Unlike the cast method, both the session and group name values must not be null, because the multicast is enabled only for a specific group.

      Parameters:
      cme - - the CM event
      sessionName - - the target session name
      groupName - - the target group name
      Returns:
      true if the event is successfully multicasted; false otherwise.
      See Also:

    • broadcast

      public boolean broadcast(CMEvent cme)
      Sends a CM event to all connected nodes.

      This method is the same as calling broadcast(cme, CMInfo.CM_STREAM, 0) of the broadcast(CMEvent, int, int) method.

      Parameters:
      cme - - the CM event
      Returns:
      true if the event is successfully broadcasted; false otherwise.
      See Also:

    • broadcast

      public boolean broadcast(CMEvent cme, int opt)
      Sends a CM event to all connected nodes.

      This method is the same as calling broadcast(cme, opt, 0) of the broadcast(CMEvent, int, int) method.

      Parameters:
      cme - the CM event
      opt - - the reliability option.
      If opt is CMInfo.CM_STREAM (or 0), CM uses TCP socket channel to send the event. If opt is CMInfo.CM_DATAGRAM (or 1), CM uses UDP datagram socket channel.
      Returns:
      true if the event is successfully broadcasted; false otherwise.
      See Also:

    • broadcast

      public boolean broadcast(CMEvent cme, int opt, int nChNum)
      Sends a CM event to all connected nodes.

      This method is the same as calling broadcast(cme, opt, 0) of the broadcast(CMEvent, int, int) method.
      The broadcast method sends a CM event to all users who currently log in to the default server via multiple one-to-one transmissions.

      Parameters:
      cme - the CM event
      opt - - the reliability option.
      If opt is CMInfo.CM_STREAM (or 0), CM uses TCP socket channel to send the event. If opt is CMInfo.CM_DATAGRAM (or 1), CM uses UDP datagram socket channel.
      nChNum - - the channel key.
      If the application adds additional TCP or UDP channels, they are identified by the channel key. The key of the TCP channel should be greater than 1 (0 for the default channel), and the key of the UDP channel is the locally bound port number.
      Returns:
      true if the event is successfully broadcasted; false otherwise.
      See Also:

    • send

      public boolean send(CMEvent cme, String serverName, String userName)
      Sends a CM event to a single node via a designated server.

      This method is the same as calling send(cme, serverName, userName, CMInfo.CM_STREAM, 0) of the send(CMEvent, String, String, int, int) method.

      Parameters:
      cme - - the CM event
      serverName - - the server name
      userName - - the target user name
      Returns:
      true if the event is successfully sent; false otherwise.
      See Also:

    • send

      public boolean send(CMEvent cme, String serverName, String userName, int opt)
      Sends a CM event to a single node via a designated server.

      This method is the same as calling send(cme, serverName, userName, opt, 0) of the send(CMEvent, String, String, int, int) method.

      Parameters:
      cme - - the CM event
      serverName - - the server name
      userName - - the target user name
      opt - - the reliability option.
      If opt is CMInfo.CM_STREAM (or 0), CM uses TCP socket channel to send the event. If opt is CMInfo.CM_DATAGRAM (or 1), CM uses UDP datagram socket channel.
      Returns:
      true if the event is successfully sent; false otherwise.
      See Also:

    • send

      public boolean send(CMEvent cme, String serverName, String userName, int opt, int nChNum)
      Sends a CM event to a single node via a designated server.

      This method is usually used to send an event to a participating user node through the designated server. This method is the same as calling send(cme, userName, opt, 0, false) of the send(CMEvent, String, int, int, boolean) method except that this method uses the designated server.
      This method is used especially if the application uses multiple servers and the client wants to send an event to another client. The target client (user) is connected to a server which is not the default server.

      Parameters:
      cme - - the CM event
      serverName - - the server name
      userName - - the target user name
      opt - - the reliability option.
      If opt is CMInfo.CM_STREAM (or 0), CM uses TCP socket channel to send the event. If opt is CMInfo.CM_DATAGRAM (or 1), CM uses UDP datagram socket channel.
      nChNum - - the channel key.
      If the application adds additional TCP or UDP channels, they are identified by the channel key. The key of the TCP channel should be greater than 1 (0 for the default channel), and the key of the UDP channel is the locally bound port number.
      Returns:
      true if the event is successfully sent; false otherwise.
      See Also:

    • cast

      public boolean cast(CMEvent cme, String serverName, String sessionName, String groupName)
      Sends a CM event to a node group via a designated server.

      This method is the same as calling cast(cme, serverName, sessionName, groupName, CMInfo.CM_STREAM, 0) of the cast(CMEvent, String, String, String, int, int) method.

      Parameters:
      cme - - the CM event
      serverName - - the server name
      sessionName - - the target session name
      If sessionName is null (not specified), the event is sent to all sessions. In this case, the groupName parameter must be also null.
      groupName - - the target group name
      If groupName is null (not specified), the event is sent to all groups in a session.
      Returns:
      true if the event is successfully sent; false otherwise.
      See Also:

    • cast

      public boolean cast(CMEvent cme, String serverName, String sessionName, String groupName, int opt)
      Sends a CM event to a node group via a designated server.

      This method is the same as calling cast(cme, serverName, sessionName, groupName, opt, 0) of the cast(CMEvent, String, String, String, int, int) method.

      Parameters:
      cme - - the CM event
      serverName - - the server name
      sessionName - - the target session name
      If sessionName is null (not specified), the event is sent to all sessions. In this case, the groupName parameter must be also null.
      groupName - - the target group name
      If groupName is null (not specified), the event is sent to all groups in a session.
      opt - - the reliability option.
      If opt is CMInfo.CM_STREAM (or 0), CM uses TCP socket channel to send the event. If opt is CMInfo.CM_DATAGRAM (or 1), CM uses UDP datagram socket channel.
      Returns:
      true if the event is successfully sent; false otherwise.
      See Also:

    • cast

      public boolean cast(CMEvent cme, String serverName, String sessionName, String groupName, int opt, int nChNum)
      Sends a CM event to a node group via a designated server.

      This method is usually used to send an event to a participating user node group through the designated server. This method is the same as calling cast(cme, sessionName, groupName, opt, nChNum) of the cast(CMEvent, String, String, int, int) method except that this method uses the designated server.
      This method is used especially if the application uses multiple servers and the client wants to send an event to a client group. The target client (user) group is connected to a server which is not the default server.

      Parameters:
      cme - - the CM event
      serverName - - the server name
      sessionName - - the target session name
      If sessionName is null (not specified), the event is sent to all sessions. In this case, the groupName parameter must be also null.
      groupName - - the target group name
      If groupName is null (not specified), the event is sent to all groups in a session.
      opt - - the reliability option.
      If opt is CMInfo.CM_STREAM (or 0), CM uses TCP socket channel to send the event. If opt is CMInfo.CM_DATAGRAM (or 1), CM uses UDP datagram socket channel.
      nChNum - - the channel key.
      If the application adds additional TCP or UDP channels, they are identified by the channel key. The key of the TCP channel should be greater than 1 (0 for the default channel), and the key of the UDP channel is the locally bound port number.
      Returns:
      true if the event is successfully sent; false otherwise.
      See Also:

    • getTransferedFileHome

      public Path getTransferedFileHome()
      Gets the default file path for file transfer.
      Returns:
      the default file path for file transfer
      See Also:

    • requestFile

      public boolean requestFile(String strFileName, String strFileOwner)
      Requests to transfer a file from a owner (pull mode).

      This method is the same as calling requestFile(strFileName, strFileOwner, CMInfo.FILE_DEFAULT) of the requestFile(String, String, byte).

      Parameters:
      strFileName - - the requested file name
      strFileOwner - - the file owner name
      Returns:
      true if the permit for receiving a file is successfully requested to the file owner, or false otherwise.
      See Also:

    • requestFile

      public boolean requestFile(String strFileName, String strFileOwner, byte byteFileAppend)
      Requests to transfer a file from a owner (pull mode).

      A client or a server can request a file from an owner node. The owner can also be a client or server.
      If the requester calls this method, the file owner receives the request event (CMFileEvent.REQUEST_PERMIT_PULL_FILE). The file owner then accepts or rejects to send the requested file automatically or manually. If the PERMIT_FILE_TRANSFER field of the owner's CM configuration file (cm-server.conf or cm-client.conf) is set to 1, the owner automatically accepts the request and proceeds the next step to send the file. If the PERMIT_FILE_TRANSFER field is set to 0, the owner application should notify CM of the answer of the request by calling replyEvent(CMEvent, int). The second parameter of this method indicates the answer. If the parameter value is 1, the request is accepted. If the parameter is 0, the request is rejected. If the requested file does not exist in the owner, the reply parameter is set to -1.
      The requester application can catch the reply event (CMFileEvent.REPLY_PERMIT_PULL_FILE) to check whether the request is accepted or not.

      CM uses two strategies in the file-transfer service. If the FILE_TRANSFER_SCHEME field of the server configuration file (cm-server.conf) is set to 0, CM uses the default communication channel between a sender and a receiver to transfer a file. If both the sender and the receiver are clients in the client-server model, then the server relays all the events required to transfer a file.
      If the FILE_TRANSFER_SCHEME field is set to 1, CM uses a separate and dedicated communication channel and thread to transfer a file. The dedicated channel is directly connected between the sender and the receiver before the file-transfer task. If a receiver node is located in a different private network, a sender cannot make a dedicated channel and cannot transfer a file.
      According to the file-transfer method, CM nodes exchanges different CM events. An easy way to figure out to which file-transfer method a CM event belongs is to check whether the event name ends with "CHAN" or "CHAN_ACK". If so, such an event belongs to the file-transfer using a dedicated channel; otherwise, the event belongs to the file-transfer using the default channel.

      When the requested file is completely transferred, the sender CM sends CMFileEvent.END_FILE_TRANSFER or CMFileEvent.END_FILE_TRANSFER_CHAN events to the requester according to the file-transfer method. The requester can catch the completion event in the event handler if it needs to be notified when the entire file is transferred.

      Parameters:
      strFileName - - the requested file name
      strFileOwner - - the file owner name
      byteFileAppend - - the file reception mode
      The file reception mode specifies the behavior of the receiver if it already has the entire or part of the requested file. CM provides three file reception modes which are default, overwrite, and append mode. The byteFileAppend parameter can be one of these three modes which are CMInfo.FILE_DEFAULT(-1), CMInfo.FILE_OVERWRITE(0), and CMInfo.FILE_APPEND(1). If the byteFileAppend parameter is CMInfo.FILE_DEFAULT, the file reception mode is determined by the FILE_APPEND_SCHEME field of the CM configuration file. If the byteFileAppend parameter is set to one of the other two values, the reception mode of this requested file does not follow the CM configuration file, but this parameter value. The CMInfo.FILE_OVERWRITE is the overwrite mode where the receiver always receives the entire file even if it already has the same file. The CMInfo.FILE_APPEND is the append mode where the receiver skips existing file blocks and receives only remaining blocks.
      Returns:
      true if the permit for receiving a file is successfully requested to the file owner, or false otherwise.
      See Also:

    • pushFile

      public boolean pushFile(String strFilePath, String strFileReceiver)
      Sends a file to a receiver (push mode).

      This method is the same as calling pushFile(strFilePath, strFileReceiver, CMInfo.FILE_DEFAULT) of the pushFile(String, String, byte).

      Parameters:
      strFilePath - - the path name of a file to be sent
      strFileReceiver - - the file receiver name
      Returns:
      true if the permit for pushing a file is successfully requested to the receiver, or false otherwise.
      See Also:

    • pushFile

      public boolean pushFile(String strFilePath, String strReceiver, byte byteFileAppend)
      Sends a file to a receiver (push mode).

      Unlike the pull mode, in the push mode, a CM client or server can send a file to another remote CM client or server if the push-file request is accepted.
      If the requester calls this method, the file receiver receives the request event (CMFileEvent.REQUEST_PERMIT_PUSH_FILE). The file receiver then accepts or rejects to receive the file automatically or manually. If the PERMIT_FILE_TRANSFER field of the receiver's CM configuration file (cm-server.conf or cm-client.conf) is set to 1, the receiver automatically accepts the request and proceeds the next step to receive the file. If the PERMIT_FILE_TRANSFER field is set to 0, the receiver application should notify CM of the answer of the request by calling replyEvent(CMEvent, int). The second parameter of this method indicates the answer. If the parameter value is 1, the request is accepted. If the parameter is 0, the request is rejected.
      The requester application can catch the reply event (CMFileEvent.REPLY_PERMIT_PUSH_FILE) to check whether the request is accepted or not.

      CM uses two strategies in the file-transfer service. If the FILE_TRANSFER_SCHEME field of the server configuration file (cm-server.conf) is set to 0, CM uses the default communication channel between a sender and a receiver to transfer a file. If both the sender and the receiver are clients in the client-server model, then the server relays all the events required to transfer a file.
      If the FILE_TRANSFER_SCHEME field is set to 1, CM uses a separate and dedicated communication channel and thread to transfer a file. The dedicated channel is directly connected between the sender and the receiver before the file-transfer task. If a receiver node is located in a different private network, a sender cannot make a dedicated channel and cannot transfer a file.
      According to the file-transfer method, CM nodes exchanges different CM events. An easy way to figure out to which file-transfer method a CM event belongs is to check whether the event name ends with "CHAN" or "CHAN_ACK". If so, such an event belongs to the file-transfer using a dedicated channel; otherwise, the event belongs to the file-transfer using the default channel.

      When the receiver receives the file completely from the requester (sender), the receiver CM sends CMFileEvent.END_FILE_TRANSFER_ACK or CMFileEvent.END_FILE_TRANSFER_CHAN_ACK events to the requester according to the file-transfer method. The requester can catch the completion event in the event handler if it needs to be notified when the receiver receives the entire file blocks.

      Parameters:
      strFilePath - - the path name of a file to be sent
      strReceiver - - the file receiver name
      byteFileAppend - - the file reception mode
      The file reception mode specifies the behavior of the receiver if it already has the entire or part of the requested file. CM provides three file reception modes which are default, overwrite, and append mode. The byteFileAppend parameter can be one of these three modes which are CMInfo.FILE_DEFAULT(-1), CMInfo.FILE_OVERWRITE(0), and CMInfo.FILE_APPEND(1). If the byteFileAppend parameter is CMInfo.FILE_DEFAULT, the file reception mode is determined by the FILE_APPEND_SCHEME field of the CM configuration file. If the byteFileAppend parameter is set to one of the other two values, the reception mode of this requested file does not follow the CM configuration file, but this parameter value. The CMInfo.FILE_OVERWRITE is the overwrite mode where the receiver always receives the entire file even if it already has the same file. The CMInfo.FILE_APPEND is the append mode where the receiver skips existing file blocks and receives only remaining blocks.
      Returns:
      true if the permit for pushing a file is successfully requested to the receiver, or false otherwise.
      See Also:

    • cancelPushFile

      public boolean cancelPushFile(String strReceiver)
      Cancels sending (or pushing) a file.

      A sender can cancel all of its sending tasks to the receiver by calling this method. The file pushing task can be cancelled regardless of the file transfer scheme that is determined by the FILE_TRANSFER_SCHEME field of the server CM configuration file. The cancellation is also notified to the receiver. The result of the receiver's cancellation is sent to the sender as CMFileEvent.CANCEL_FILE_SEND_ACK or CMFileEvent.CANCEL_FILE_SEND_CHAN_ACK event.

      Parameters:
      strReceiver - - the receiver name
      Returns:
      true if the cancellation is succeeded, or false otherwise.
      See Also:

    • cancelPullFile

      public boolean cancelPullFile(String strSender)
      Cancels receiving (or pulling) a file.

      A receiver can cancel all of its receiving tasks from the sender by calling this method. Unlike the cancellation of the file pushing task, the file pulling task can be cancelled only if the file transfer scheme uses the separate channel (, that is, if the FILE_TRANSFER_SCHEME field is 1 in the server CM configuration file). The cancellation is also notified to the sender. The result of the sender's cancellation is sent to the receiver as CMFileEvent.CANCEL_FILE_RECV_CHAN_ACK event.

      Parameters:
      strSender - - the sender name
      Returns:
      true if the cancellation is succeeded, or false otherwise.
      See Also:

    • measureInputThroughput

      public double measureInputThroughput(String strTarget)
      measures the incoming network throughput from a CM node.

      A CM application can measure the incoming/outgoing network throughput from/to another CM application (server or client). The incoming network throughput of a CM node A from B measures how many bytes A can receive from B in a second. The outgoing network throughput of a CM node A to B measures how many bytes A can send to B.

      Parameters:
      strTarget - - the target CM node
      The target CM node should be directly connected to the calling node.
      Returns:
      the network throughput value by the unit of Megabytes per second (MBps) if successfully measured, or -1 otherwise.
      See Also:

    • measureOutputThroughput

      public double measureOutputThroughput(String strTarget)
      measures the outgoing network throughput to a CM node.
      Parameters:
      strTarget - - the target CM node
      Returns:
      the network throughput value by the unit of Megabytes per second (MBps) if successfully measured, or -1 otherwise.
      See Also:

    • getCurrentChannelInfo

      public String getCurrentChannelInfo()
      gets the string representation of current channels information.

      This method in the CMStub class gets only the blocking/non-blocking datagram channel information. The CMClientStub.getCurrentChannelInfo() and CMServerStub.getCurrentChannelInfo() methods get the current blocking/non-blocking socket channel information as well as the datagram channels.

      Returns:
      string of current channels information if successful, or null otherwise.
      See Also:

    • setConfigurationHome

      public void setConfigurationHome(Path homePath)
      sets a path to the CM configuration file.

      After calling this method, when CM needs to access the configuration file, CM finds it (cm-server.conf for the server CM and cm-client.conf for the client CM) in this path.

      Parameters:
      homePath - the path to the CM configuration file
      See Also:

    • getConfigurationHome

      public Path getConfigurationHome()
      gets the path to the CM configuration file.

      If the CM client needs to access the configuration file, the path to it can be retrieved as follows:

      cmClientStub.getConfigurationHome().resolve("cm-client.conf");

      cmClientStub is the reference to a CM client-stub object.
      If the CM server needs to access its configuration file, the path to it can be retrieved as follows:

      cmServerStub.getConfigurationHome().resolve("cm-server.conf");
      cmServerStub is the reference to a CM server-stub object.

      Returns:
      the path to the CM configuration file
      See Also:

    • getThreadInfo

      public String getThreadInfo()
      gets the current thread pool information.
      Returns:
      the current thread pool information string