ipworks
Class Mx

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

public class Mx

extends java.lang.Object

The MX bean enables querying of mail exchange (MX) records from a Domain Name Server (DNS). That is, it will find out the name(s) of the mail server(s) accepting email for a given email address or domain.

The bean will attempt to automatically determine the name of a DNS server from the system settings or from the value of the DNSServer property.

The bean operates in synchronous or asynchronous mode, depending on the value of the Timeout property. Assigning an email address or domain name to the EmailAddress property directs the bean to query the DNSServer . The Response event is fired for each server that handles mail for the email address. The bean will fill out the MailServer property with the most preferred mail server and the Status property to "Ok" or an error message.

The RequestId property may be used to identify requests and is used in the Response event. The user may set its value before sending out requests, and then match the responses to the request using the RequestId parameter in the Response event.

Constructor Summary

Mx()

Method Summary

void	addMxEventListener(ipworks.MxEventListener l)
java.lang.String	config(java.lang.String configurationString) Sets or retrieves a beanconfiguration setting.
void	doEvents() Processes events from the internal message queue.
int	getDNSPort() The port where the DNS server is listening.
java.lang.String	getDNSServer() The address of the DNS Server.
java.lang.String	getLocalHost() The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
java.lang.String	getMailServer() Mail server with lowest precedence value (lowest cost to reach).
int	getRequestId() Identifies each request.
java.lang.String	getStatus() Status of the request: empty while in progress, 'OK' or error message upon completition.
int	getTimeout() A timeout for the bean.
void	interrupt() Interrupt the current method.
boolean	isIdle() The current status of the component.
void	removeMxEventListener(ipworks.MxEventListener l)
void	resolve(java.lang.String emailAddress) Resolve an email address.
void	setDNSPort(int DNSPort) The port where the DNS server is listening.
void	setDNSServer(java.lang.String DNSServer) The address of the DNS Server.
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	setRequestId(int requestId) Identifies each request.
void	setTimeout(int timeout) A timeout for the bean.

Methods inherited from class java.lang.Object

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

Constructor Detail

Mx

public Mx()

Method Detail

getDNSPort

public int getDNSPort()

The port where the DNS server is listening.

The default value is 53 but you may set DNSPort to any other value for use with experimental servers, etc.

setDNSPort

public void setDNSPort(int DNSPort)
                throws IPWorksException

The port where the DNS server is listening.

The default value is 53 but you may set DNSPort to any other value for use with experimental servers, etc.

IPWorksException

getDNSServer

public java.lang.String getDNSServer()

The address of the DNS Server.

The bean attempts to find the default DNS server for the machine where it is installed, and provide it in the DNSServer property. You may later change it to any particular DNS server you want to query. While any internet host running a DNS service will suffice, it is preferable to use either the DNS server for your network or the DNS server for the domain which you are querying.

If the bean cannot determine the default DNS server address, the property value will be an empty string.

setDNSServer

public void setDNSServer(java.lang.String DNSServer)
                  throws IPWorksException

The address of the DNS Server.

The bean attempts to find the default DNS server for the machine where it is installed, and provide it in the DNSServer property. You may later change it to any particular DNS server you want to query. While any internet host running a DNS service will suffice, it is preferable to use either the DNS server for your network or the DNS server for the domain which you are querying.

If the bean cannot determine the default DNS server address, the property value will be an empty string.

IPWorksException

isIdle

public boolean isIdle()

The current status of the component.

Idle will be False if the component is currently busy (communicating and/or waiting for an answer), and True at all other times.

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

getMailServer

public java.lang.String getMailServer()

Mail server with lowest precedence value (lowest cost to reach).

After all events are fired the MailServer property holds the name of the best mail server for the EmailAddress and the Status property holds the completion status.

getRequestId

public int getRequestId()

Identifies each request.

This may be useful if several email addresses need to be resolved. Each request may be identified by the user before starting a query (setting the EmailAddress property).

If a custom value is needed for RequestId , the property must be set before setting EmailAddress . The bean increments RequestId automatically after sending each request.

setRequestId

public void setRequestId(int requestId)
                  throws IPWorksException

Identifies each request.

This may be useful if several email addresses need to be resolved. Each request may be identified by the user before starting a query (setting the EmailAddress property).

If a custom value is needed for RequestId , the property must be set before setting EmailAddress . The bean increments RequestId automatically after sending each request.

IPWorksException

getStatus

public java.lang.String getStatus()

Status of the request: empty while in progress, 'OK' or error message upon completition.

The Status property is reset each time a request is made by setting EmailAddress . When a response comes from the DNSServer the Status property is set to "OK" in case of success or to an error message as described in the Response event.

getTimeout

public int getTimeout()

A timeout for the bean.

If the Timeout property is set to 0, all operations return immediately, potentially failing with an error if they can't be completed immediately.

If Timeout is set to a positive value, the bean will wait for the operation to complete before returning control.

The bean will use DoEvents to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and remains responsive.

If Timeout expires, and the operation is not yet complete, the bean throws an IPWorksException raises an IPWorksException exception .

Please note that by default, all timeouts are inactivity timeouts , i.e. the timeout period is extended by Timeout seconds when data is successfully sent or received.

Optionally, the behaviour of the bean may be changed to absolute timeouts , i.e. the bean will wait for a maximum of Timeout seconds since the beginning of the operation, without extending the timeout period during communications.

This behavior is controlled by theAbsoluteTimeoutconfiguration setting.

The default value for the Timeout property is 60 seconds.

setTimeout

public void setTimeout(int timeout)
                throws IPWorksException

A timeout for the bean.

If the Timeout property is set to 0, all operations return immediately, potentially failing with an error if they can't be completed immediately.

If Timeout is set to a positive value, the bean will wait for the operation to complete before returning control.

The bean will use DoEvents to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and remains responsive.

If Timeout expires, and the operation is not yet complete, the bean throws an IPWorksException raises an IPWorksException exception .

Please note that by default, all timeouts are inactivity timeouts , i.e. the timeout period is extended by Timeout seconds when data is successfully sent or received.

Optionally, the behaviour of the bean may be changed to absolute timeouts , i.e. the bean will wait for a maximum of Timeout seconds since the beginning of the operation, without extending the timeout period during communications.

This behavior is controlled by theAbsoluteTimeoutconfiguration setting.

The default value for the Timeout property is 60 seconds.

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

interrupt

public void interrupt()
               throws IPWorksException

Interrupt the current method.

If there is no method in progress, Interrupt simply returns doing nothing.

IPWorksException

resolve

public void resolve(java.lang.String emailAddress)
             throws IPWorksException

Resolve an email address.

Calling this method directs the bean to query DNSServer at port DNSPort about MX records related to EmailAddress .

The server's response is provided through one or more Response events.

After the query completes, the MailServer property is set to the best mail server and the Status property has the result description of the response.

Valid queries are email addresses like name@company.com or hostnames and domains like domain.com .

Example (Determine Top Priority Mail Server of Email Address)

 MXControl.Resolve "email@server.com"
 While MXControl.MailServer = ""
 \011MXControl.DoEvents()
 End While
 BestMailServer = MXControl.MailServer 

IPWorksException

addMxEventListener

public void addMxEventListener(ipworks.MxEventListener l)
                        throws java.util.TooManyListenersException

java.util.TooManyListenersException

removeMxEventListener

public void removeMxEventListener(ipworks.MxEventListener l)