 |
Description
|
This bean provides POP3
CoreProtocolBean client services. These include user authentication,
receiving messages and deleting messages from a POP3 server.
The bean listens for commands from
a bean which implements the user interface. Commands can be passed to this
bean either wrapped as a RequestMessageEvent
object or by calling the receiveMessage
method after configuring the POP3 server and socks server hosts.
The bean also listens for
configuration event (ConfigEvent).
It receives information about the bean configuration, including the POP3
server host and port number, socks server host and port number, and user
information through this event. This information can also be set at the
CoreProtocolBean using API methods setPOP3Server,
setSocksServer,
setUserOptions
etc.
The bean fires the StatusEvent
containing relevant data about the status of the request for receiving
messages. This is captured by the UserInterfaceBean, and the status
contained is displayed to the user.
The bean also fires a MessageEvent
which contains the messages received from the POP3 server. The user
interface captures this event, and displays the received message to the
user.
Significant events
The bean fires the following
events, which a user interface component would need to capture :
- StatusEvent
which carries the status of the request for receiving messages.
- MessageEvent
which carries the message received from the POP3 server.
Significant methods
The POP3 CoreProtocolBean
implements the following significant methods:
- Adding / removing listeners for
events (described above) fired by this class:
- Methods that service external
events
- Methods that provide requested
service
- Methods that set / query the
state of the CoreProtocolBean :
Note
: The parameters to the setter methods should not be 'null' or 'empty'
in case of a string. Doing so will result in throwing of
IllegalArgumentException
- Methods used to configure the
system
- Methods that may be used by the
application to issue commands to the CoreProtocolBean. The application
menu or toolbar would provide the interface to call these methods.
- abort
- When called by the application container the
current operation of receiving messages, if any, is aborted.
Customization
The following attributes of the
POP3 CoreProtocolBean can be customized.
- LeaveMessagesOnServer
- indicates whether messages are to be left on server after receiving.
- LoginId -
POP3 login ID of the user.
- RememberPassword
- indicates whether the password of the user should be remembered.
- POP3ServerHost
- hostname / IP address of the POP3 server.
- POP3ServerPort
- port number to be used of the POP3 server.
- SocksServerHost -
hostname / IP address of the socks server.
- SocksServerPort -
port number to be used of the socks server.
- Socksified -
boolean value which determines whether the socks server is to be used.
- SaveIncomingMessages
- indicates whether incoming messages should be saved to a file.
- SaveMessagesToFile
- file where incoming messages should be saved. In some IDE's the path name, if set in property sheet should use "\\"
to specify the path.
- Ready
- a read-only bound property. When the CoreProtocolBean is not receiving
any mails, this property is true, and false when messages are being
received. This property value can be linked to the applications option
for receiving message. Since this is a read-only property, this will not
be shown in the property sheet of the IDE. In case it is shown, it will
be a non-editable property.
The property "Ready"
needs some more explanation. This is a boolean property and its value
remains true when the bean is ready to receive messages. It becomes
false when it starts receiving messages and remains false until the
operation of receiving messages completes or an error is encountered.
The CoreProtocolBean spawns a new thread of control for every request
for receiving messages. An application container using this bean will
typically have a menu item or a button "receive message".
The "Ready" property of the bean can be bound to the "enabled"
property of this GUI item. The option will be enabled when no messages
are currently being received, and when messages are being received,
this option will be disabled to prevent another simultaneous request.
The UserInterfaceBean implements a
user interface to view the received messages. It provides a mechanism for
interacting with the CoreProtocolBean for making a connection to a POP3
server and receiving mails.Once the messages are received, the message
header which contains the message subject, sender's name, and date are
shown as a list.
The UserInterfaceBean passes
configuration information about the POP3 server, socks server and user
details by throwing the ConfigEvent
whenever the user modifies this data. This is caught by the
CoreProtocolBean and used in making connections to a POP3 server.
The UserInterfaceBean requests the
CoreProtocolBean to retrieve the messages from the configured server by
throwing a RequestMessageEvent
While the CoreProtocolBean is
making a connection to the POP3 server or while retrieving the messages,
the status information received is bundled and fired as a StatusEvent
by the CoreProtocolBean. This status event is
captured by the UserInterfaceBean and displayed to the user.
Once the messages are received, the
message header which contains the message subject, sender's name and date,
are shown as a list. The user may choose to view any of the messages shown
in the list. On user request to view a message, the UserInterfaceBean
analyses the contents to determine which of the message parts can be
rendered by it. These are the parts which contain plain text. For each
such part, the UserInterfaceBean fires DecodeMessageEvent
containing the part to be decoded. Other parts like attachments are not
requested to be decoded at this point in order to optimize the
performance, as decoding large attachments is a time consuming process and
it is possible that a user may not want all the body parts to be decoded.
When the decoder bean completes
decoding the requested data, it throws a DecodeEvent
which is captured by the UserInterfaceBean, and the UserInterfaceBean
displays the decoded data in the Message Text Area
and attachments, if any, in the Attachments Panel. The user may choose to
detach ( save in a file) any of the attachments. When the user chooses to
detach any of the attachment(s), the UserInterfaceBean requests the
decoder bean to decode the relevant body part by throwing DecodeMessageEvent.
When the decoder bean completes decoding the body part, it throws a
DecodeEvent
which is caught by the UserInterfaceBean and the decoded part is saved to
the given filename.
Significant Events
RequestMessageEvent
- This event is fired to the CoreProtocolBean. This requests the
CoreProtocolBean to retrieve messages from the POP3 server.
DecodeMessageEvent
- It is fired to the decoder bean to request decoding of a part of a
message.
ConfigEvent
- This event is fired to the CoreProtocolBean to configure the POP3 and
socks servers' hostname and port numbers to be used, and the user's ID and
password for the given POP3 server.
Significant Methods
- Methods to add / remove
listeners for the events fired by the bean
- Methods that listen to events
from the MimeDecoder / CoreProtocol beans
- decodePerformed
- when the decoder bean has decoded a part of a message.
- processStatus
- listens for status events from the CoreProtocolBean.
- messageReceived
- gets received messages from CoreProtocolBean and displays their
headers in the Inbox.
- Methods that may be used by the
application container to set/query message items.This list is a
representative sample :
Note
: The parameters to the setter methods should not be 'null' or 'empty'
in case of a string. Doing so will result in throwing of
IllegalArgumentException
- getLoginId
-returns the current user's login ID.
- setLoginId
- sets the user's login ID.
- getFolderDirectory
- returns the directory where the folders containing messages are
located.
- setFolderDirectory
- sets the directory where message folders are
saved. All folders use a common file called "messages" for
storing messages. In addition, each folder has information that is
relevant to it, stored in a separate file ("<folder-name>.summary").
All these files are stored in the "folder directory".
- getMessage
- returns the message.
- getUserPassword
- returns the password of the current user.
- setUserPassword
- sets the password for the current user.
- getUserOptions
- returns the configured user options.
- setUserOptions
- configures the user options.
- getPOP3Server
- returns the server options specified while configuring the server
information.
- setPOP3Server
- sets the POP3 server configuration.
- getPOP3ServerHost
- returns the hostname / IP address of the current POP3 server.
- setPOP3ServerHost
- returns the hostname / IP address of the desired POP3 server.
- getPOP3ServerPort
- returns the port number of the POP3 server.
- setPOP3ServerPort
- sets the port number of the POP3 server.
- getSocksServer
- returns the socks server options specified while configuring the
server information.
- setSocksServer
- sets the socks server configuration.
- getSocksServerHost
- returns the hostname / IP address of the current socks server.
- setSocksServerHost
- sets the hostname / IP address of the desired socks server.
- getSocksServerPort
- returns the port number of current socks server.
- setSocksServerPort
- sets the port number of desired socks server.
- setSocksified
- enables/disables use of socks server.
- getHeaderCaptionWidths
- returns the width of the header
captions.
- setHeaderCaptionWidths
- sets the caption widths in the UserInterfaceBean for header
information. The sizes of fields "Date", "Sender",
"Subject" and "Status" are set to those
specified.
- getCCRecipients
- returns a comma seperated list of "Cc"
recipients
- getTORecipients
- returns a comma seperated list of "To"
recipients.
- getBCCRecipients
- returns a comma seperated list of "Bcc"
recipients
- getBody-
returns the body of the currently selected message
- getSubject
- returns the "Subject" of the
currently selected message
- getSender
- returns the sender ("From") of the
currently selected message
- Methods that may be used by the
application to issue commands to the UserInterfaceBean, an application
menu or toolbar would typically provide the interface to these methods :
- configure
- when called by the application container, the
configure dialog is displayed.
- receiveMessage
- called by the application to receive messages.
- deleteSelectedMessage
- called by the application to delete the
selected message from the current folder.
- emptyTrashFolder
- called by the application to empty the contents of the trash
folder.
- ChangeUserPassword
- called by the application to change the user's login password.
The following attributes of the
POP3 UserInterfaceBean can be customized :
Customization
- POP3ServerHost -hostname
/ IP address of the POP3 server.
- POP3ServerPort -
port number of the POP3 server (well known default port is 110).
- SocksServerHost -
hostname / IP address of the socks server.
- SocksServerPort -
port number of the socks server (default port is 1080).
- Socksified
- 'true' if socks server is to be used .
- StatusBarVisible -
'true' if the status bar at the bottom of the UserInterfaceBean should
be visible.
- RememberPassword -
'true' if user password should be remembered .
- FolderDirectory -
full path name of the directory which contains messages
file. In some IDE's the path name, if set in property sheet should use "\\"
to specify the path. e.g. to specify "c:\demo", use "c:\\demo".
- DisplayAllHeaders -
'true' if the entire mail header is to be displayed in the Message
Dispaly Area.
- LoginId -
POP3 login ID of user for given server.
- LeaveMessagesOnServer -
whether messages should be left on server after reading.
- HeaderCaptionWidths - caption
widths in the UserInterfaceBean for header information. The sizes of
fields "Date", "Sender", "Subject" and "Status"
are set to those specified
Note
: The property cannot be set in BeanBox, since it requires a
property editor for it. It can be set only in IDE's that have a default
property editor for this type of property (integer array).
- Status-
status of request to receive mails. "Status" is a read-only
bound property. The status bar is customizable in that it can be made
invisible when the application container itself has a status bar. In
this case, all the status information of the bean can be displayed on
the status bar of the application container by binding the property "Status"
of the bean to the application's status bar. Since this is a read-only
property, this will not be shown in the property sheet of the IDE. In
case it is shown, it will be a non-editable property.
The property "Status" needs some more
explanation. The UserInterfaceBean contains its own status bar at the
bottom. Typically, an application container which uses this bean, will
have its own status bar. If so, the application container may prefer
to display all the status information on its status bar. The bean's
status bar can be made invisible and the "Status" property
can be bound to the status bar of the application container. Thus, all
the status information will appear on the application's status bar.
This bean decodes a MimeMessage.
At present it is minimal Mime compliant (as defined in RFC 1521). The bean
supports "base 64" and "7 bit" encoding.
The bean listens to commands from
the bean which implements the user interface. Commands can be passed to
this bean either wrapped as a DecodeMessageEvent
object or by calling the decodeBodyPart
method with an object of type Decodable,
both of which process the desired request. It listens for DecodeMessageEvent
from the UserInterfaceBean by implementing the decodeBodyPart
method which accepts a DecodeMessageEvent.
This bean fires theDecodeEvent
to notify completion of decoding of a part of a MIME message. The bean can
also decode a complete message or any MIME data input stream.
Significant Events
- The bean fires the following
event, which a user interface component would need to capture:
- DecodeEvent
- which indicates completion of decoding
of a part of a MIME message. The event is fired in response to a
request to decode a part of a MIME message
Significant Methods
The POP3 MimeDecoderBean implements
the following significant methods :
- Adding / removing listeners for
DecodeEvent
fired by this bean:
- Methods that accept external
events
- Methods that may be used to
request services as an alternate mechanism to using events
- decodeData
- decodes the data in input stream
depending on the content type (either "base64"or
"7bit").
- decodeMessage
- accepts message to be decoded as a MimeMessage
object.
Customization
This bean contains no customizable
properties.
Refer to the section Usage
Scenarios for information on how to use the POP3 suite of beans
in different ways.