SK.gnome.dwarf.mail.smtp
Class Recipient

java.lang.Object
  extended bySK.gnome.dwarf.mail.smtp.Recipient
All Implemented Interfaces:
java.lang.Cloneable, java.io.Serializable

public class Recipient
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable

This class represents a mail recipient.

It models a single recipient of mail message. Since the recipients are initialized from the SMTP envelope, the recipient address is always in the form of local-part@domain, as stated in RFC 2821.

A recipient is always in one of the defined states represented by the NEW, EXPANDED, DELIVERED, RELAYED, DEFERRED, FAILED and REJECTED constants, as returned from the getState() method. According to this state the recipient is regarded as finished or not, which may by checked also by the isFinished() method. Currently, a recipient is finished if it is neither new, nor deferred.

A new Delivery instance may be added to the recipient to represent either a successful or a failed delivery attempt. The same effect may be gained by calling the finish(int, String, String) method.

See Also:
Serialized Form

Field Summary
static int DEFERRED
          This state represents recipients for which the message delivery has been deffered for any reason.
static int DELIVERED
          This state represents recipients for which the message has been successfully delivered to a local mailbox.
static int EXPANDED
          This state represents recipients which have been expanded to another addresses by an alias name.
static int FAILED
          This state represents recipients for which the message delivery has definitelly failed for any reason.
static int NEW
          This state represents new recipients with no delivery attempts yet.
static int REJECTED
          This state represents recipients for which the message delivery has failed because the server rejected it.
static int RELAYED
          This state represents recipients for which the message has been successfully relayed to a remote SMTP host.
 
Constructor Summary
Recipient(java.lang.String address)
          Creates a new Recipient.
 
Method Summary
protected  void addDelivery(Delivery delivery, int state)
          Adds a new delivery to the recipient.
 Recipient alias(java.lang.String address, java.lang.String defaultHost)
          Creates a new recipient based on this recipient alias.
protected  java.lang.Object clone()
           
 boolean equals(java.lang.Object obj)
           
 void finish(int state, java.lang.String status, java.lang.String message)
          Marks the recipient as finished.
 java.lang.String getAddress()
          Returns the recipient address as Unicode string.
 java.lang.String getAlias()
          Returns the recipient alias as Unicode string.
 java.util.Iterator getAllDeliveries()
          Returns all deliveries so far.
 Delivery getDeliveryAfter(long time)
          Returns the delivery just after the specified time.
 java.lang.String getHost()
          Returns the domain part of the address.
 java.lang.String getNotify()
          Returns the DSN NOTIFY parameter.
 java.lang.String getORcpt()
          Returns the DSN ORCPT parameter.
 Delivery getRecentDelivery()
          Returns the recent delivery.
 int getState()
          Returns the actual recipient state.
 java.lang.String getStateString()
          Returns the string representation of the recipient state.
 java.lang.String getUser()
          Returns the local part of the address.
 int hashCode()
           
 boolean isFinished()
          Whether the recipient is finished.
 boolean isProcessedByNode(Node node)
          Whether the recipient has been processed for the given node.
protected  void setAddress(java.lang.String address)
          Sets the recipient address.
protected  void setAlias(java.lang.String alias)
          Sets the recipient alias.
 void setNotify(java.lang.String notify)
          Sets the DSN NOTIFY parameter.
 void setORcpt(java.lang.String orcpt)
          Sets the DSN ORCPT parameter.
protected  void setState(int state)
          Sets the recipient state.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

NEW

public static final int NEW
This state represents new recipients with no delivery attempts yet.

See Also:
Constant Field Values

EXPANDED

public static final int EXPANDED
This state represents recipients which have been expanded to another addresses by an alias name.

See Also:
Constant Field Values

DELIVERED

public static final int DELIVERED
This state represents recipients for which the message has been successfully delivered to a local mailbox.

See Also:
Constant Field Values

RELAYED

public static final int RELAYED
This state represents recipients for which the message has been successfully relayed to a remote SMTP host.

See Also:
Constant Field Values

DEFERRED

public static final int DEFERRED
This state represents recipients for which the message delivery has been deffered for any reason.

See Also:
Constant Field Values

FAILED

public static final int FAILED
This state represents recipients for which the message delivery has definitelly failed for any reason.

See Also:
Constant Field Values

REJECTED

public static final int REJECTED
This state represents recipients for which the message delivery has failed because the server rejected it.

See Also:
Constant Field Values
Constructor Detail

Recipient

public Recipient(java.lang.String address)
          throws MailException,
                 AddressException
Creates a new Recipient.

The address parameter may contain any valid RFC822 address.

This constructor calls the setAddress(String) method to set the given address string.

Parameters:
address - the RFC822 address
Throws:
MailException - if an error occured
AddressException - if an address syntax error occured
Method Detail

getAddress

public java.lang.String getAddress()
Returns the recipient address as Unicode string.

Returns:
the address

getAlias

public java.lang.String getAlias()
Returns the recipient alias as Unicode string.

The alias is an address from which this recipient was expanded.

Returns:
the alias address

getUser

public java.lang.String getUser()
Returns the local part of the address.

Returns:
the mailbox name

getHost

public java.lang.String getHost()
Returns the domain part of the address.

Returns:
the domain name

getState

public int getState()
Returns the actual recipient state.

Returns:
the state

setNotify

public void setNotify(java.lang.String notify)
Sets the DSN NOTIFY parameter.

This parameter may be modified to instruct the server that it must not generate a DSN notification for the given recipient.

Parameters:
notify - the NOTIFY parameter value

getNotify

public java.lang.String getNotify()
Returns the DSN NOTIFY parameter.

Returns:
the NOTIFY parameter value

setORcpt

public void setORcpt(java.lang.String orcpt)
Sets the DSN ORCPT parameter.

Parameters:
orcpt - the ORCPT parameter value

getORcpt

public java.lang.String getORcpt()
Returns the DSN ORCPT parameter.

Returns:
the ORCPT parameter value

getRecentDelivery

public Delivery getRecentDelivery()
Returns the recent delivery.

Returns:
the recent delivery

getDeliveryAfter

public Delivery getDeliveryAfter(long time)
Returns the delivery just after the specified time.

Parameters:
time - the time
Returns:
the delivery

getAllDeliveries

public java.util.Iterator getAllDeliveries()
Returns all deliveries so far.

Returns:
the iteration of Delivery objects

finish

public void finish(int state,
                   java.lang.String status,
                   java.lang.String message)
            throws MailException
Marks the recipient as finished.

A new Delivery instance is added to the recipient with the corresponding arguments and the final state. It is error to attempt to finish an already finished recipient.

Parameters:
state - the finished recipient's state
status - the SMTP status code in the form of X.Y.Z
message - the SMTP status message
Throws:
java.lang.IllegalStateException - if the recipient is already finished
MailException - if an error occured

isFinished

public boolean isFinished()
Whether the recipient is finished.

A recipient is regarded as finished if its state is different than NEW or DEFERRED.

Returns:
true if the recipient is finished, false otherwise

isProcessedByNode

public boolean isProcessedByNode(Node node)
Whether the recipient has been processed for the given node.

Each particular recipient may be processed for the given Node object just once. This method checks if it has been done already.

Parameters:
node - the node
Returns:
true if recipient was processed by the given node, false otherwise

getStateString

public java.lang.String getStateString()
Returns the string representation of the recipient state.

Returns:
the state string

alias

public Recipient alias(java.lang.String address,
                       java.lang.String defaultHost)
                throws MailException,
                       AddressException
Creates a new recipient based on this recipient alias.

This method creates a new Recipient object with the given address if this recipient represents an alias address. If the alias does not contain a domain part, the defaultHost is used. The DSN ORCPT parameter of the new recipient is set to the alias address if the parameter's original value is null.

This method creates a new Recipient instance by calling the clone() method, therefore it must always provide a suitable implementation.

Parameters:
address - the new address
defaultHost - default domain name
Returns:
the new recipient
Throws:
MailException - if an error occured
AddressException - if an address syntax error occured

equals

public boolean equals(java.lang.Object obj)

hashCode

public int hashCode()

toString

public java.lang.String toString()

setAlias

protected void setAlias(java.lang.String alias)
Sets the recipient alias.

Parameters:
alias - the alias address

setState

protected void setState(int state)
Sets the recipient state.

Parameters:
state - the state

setAddress

protected void setAddress(java.lang.String address)
                   throws MailException,
                          AddressException
Sets the recipient address.

Parameters:
address - the address
Throws:
AddressException - if an address syntax error occured
MailException

addDelivery

protected void addDelivery(Delivery delivery,
                           int state)
Adds a new delivery to the recipient.

Each Delivery object represents a particular delivery attempt. The state parameter specifies whether the delivery was successful or not. According to the last delivery state the recipient may become finished, so it no longer needs an attention of the message delivery subsystem.

Parameters:
delivery - the delivery attempt
state - the delivery state

clone

protected java.lang.Object clone()


Copyright (c) 2004-2005, Gnome Ltd. All rights reserved.