All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class GIT.GVU.IMAP.Mailbox

java.lang.Object
   |
   +----GIT.GVU.IMAP.Mailbox

public class Mailbox

extends Object

readonly

Variable to hold our readonly state.

CHECK()

This function is called to get the server to (posibly) checkpoint its state, if that is necesary.

CLOSE()

CLOSE causes a mailbox to go away.

COPY(int, String)

This function is called to COPY a message from one mailbox to another.

EXPUNGE()

This function is called to actual delete all the messages in the mailbox with the \Deleted flag set.

FETCH(String)

Fetch a mail message from the mailbox.

FETCH(int)

Another version of FETCH() which takes an integer.

flushCache()

This is a function you can call when you want to flush the cache by hand.

getExists()

This function returns the size of the mailbox in messages.

getFlags()

This function gets the current list of flags on this mailbox.

getMessage(int)

Get a message from the message cache.

getPermanentFlags()

This function gets the current list of flags that you can modify permanently on this mailbox.

getRecent()

This function returns the number of "recent" messages in a mailbox.

isReadOnly()

This function tells you if this mailbox is readonly or not.

setExpungeAction(AsynchronousAction)

This function sets the Aysnch.Action object which is associated with EXPUNGE messages.

setRecentAction(AsynchronousAction)

This function sets up a callback AsynchronousAction which gets invoked whenever new mail is received.

  public boolean readonly

Variable to hold our readonly state.

  public boolean isReadOnly()

This function tells you if this mailbox is readonly or not. Note: see RFC1730 for some cases where you can modify the per-use state of read-only mailboxes when then are accessed via SELECT.

Returns:

true if the mailbox is read-only, false otherwise

  public int getRecent() throws InternalErr

This function returns the number of "recent" messages in a mailbox. See description of recent variable for more info.

Returns:

number of messages added to box since last read

Throws: InternalErr

is thrown if you call getRecent() and the mailbox has not seen a RECENT message yet (this should never happen)

  public int getExists() throws InternalErr

This function returns the size of the mailbox in messages.

Returns:

number of messages in a mailbox

Throws: InternalErr

is thrown if you call getExists() and the mailbox hasn't yet seen an EXIST message from the server (this should never happen)

  public Vector getFlags()

This function gets the current list of flags on this mailbox.

Returns:

the current Vector of flags (they are strings in the vector)

  public Vector getPermanentFlags()

This function gets the current list of flags that you can modify permanently on this mailbox. Note: this is an optional message from the server. It might not send it, so you must be able to handle the case when this vector is empty. Further, if you open a mailbox read- only this vector will be empty (as you can't modify that mailbox!).

Returns:

the current Vector of permanent flags (they are strings in the vector)

  public boolean FETCH(String s) throws InternalErr, IMAPException

Fetch a mail message from the mailbox. This is really a call to FETCH (FLAGS RFC822.SIZE ENVELOPE BODYSTRUCTURE), if you are looking at RFC 1730. Note: This call has the side effect of updating this mailboxes cache if necessary. If not necessary, it does nothing. Thus, call this whenever you want!

Parameters:

s - string with a message number or message sequence in it (see RFC 1730 for how to form a sequence)

Returns:

boolean if we succeed or failed

Throws: InternalErr

is propagated

Throws: IMAPException

is propagated

  public boolean FETCH(int n) throws IMAPException, InternalErr

Another version of FETCH() which takes an integer. This is just a wrapper around the real FETCH.

Parameters:

int - n message number to fetch

Returns:

true if the FETCH succeeded, false otherwise

Throws: IMAPException

is propagated

Throws: InternalErr

is propagated

  public Message getMessage(int n)

Get a message from the message cache. If you have not yet FETCHed the message, then it won't be in the cache and you'll get null. You will also get null if you ask for a message number that is out of bounds.

Parameters:

int - n message number to retreive

Returns:

the Message object corresponding to that message number

  public void flushCache()

This is a function you can call when you want to flush the cache by hand. It will be called automatically by the object itself at certain points in the protocol as necessary.

  public boolean EXPUNGE() throws InternalErr, IMAPException

This function is called to actual delete all the messages in the mailbox with the \Deleted flag set. As per RFC 1730, if there is an EXPUNGEd messages this will result in all messages with higher numbers automatically being decremented by one. This happens BEFORE this call returns, so immediately following this call, you should probably think about what the state of the message cache might be.

Returns:

bool true if the EXPUNGE call succeeded, false otherwise

Throws: IMAPException

is propagated

Throws: InternalErr

is propagated

  public boolean CLOSE() throws IMAPException, InternalErr

CLOSE causes a mailbox to go away. It updates the Connection object to reflect this. Note: If there are pending deletions (i.e. Messages marked with the \Deleted flag) they get deleted as a result of this. However, you won't get any notification of this. Note, if the CLOSE fails, then we don't tell the Connection object to drop its Mailbox.

Returns:

true if the CLOSE succeeded, false otherwise

Throws: IMAPException

is propagated

Throws: InternalErr

is propagated

  public boolean CHECK() throws InternalErr, IMAPException

This function is called to get the server to (posibly) checkpoint its state, if that is necesary. Note: This does not imply that you will get new EXISTS messages. If you want that type of stuff, use NOOP. Note: This may not instanteous. For more info on this and the differences from NOOP, see RFC 1730.

Returns:

bool true if the CHECK call succeeded, false otherwise

Throws: IMAPException

is propagated

Throws: InternalErr

is propagated

  public Boolean COPY(int n,
                      String box) throws InternalErr, IMAPException

This function is called to COPY a message from one mailbox to another. This function has three possible return values, true, false, and null. Note: these are returned as the class Boolean, not simply booleans. In other words be SURE to use the the equals() method not the == operator. Example:

Boolean b;
Mailbox m;
...
b=m.COPY(2,"~/somebox");
if (b==null) {
... try to create the mailbox ... and retry if you want ...
} else {
   if (b.equals(new Boolean(true))==true) {
       ... it worked ...
   } else {
       ... failed miserably... creating it won't help...
   }
} 

If the return value is true, the call succeded. If its false, the call failed and a attempting to create the mailbox will not help. If its null (and you better check for it) then this call failed, but using the CREATE command could create the mailbox so that retrying this call would work. Note: It seems that you might want to check for the null case first just to make sure you don't end up using a null pointer if indeed it is null.

Parameters:

int - n message number

String - box name of target mailbox

Returns:

a Boolean which is either true, false, or null (see above)

Throws: InternalErr

is propagated

Throws: IMAPException

is propagated

  public void setRecentAction(AsynchronousAction a)

This function sets up a callback AsynchronousAction which gets invoked whenever new mail is received. This is triggered by reception of the RECENT response in the IMAP protocol. Note: when you first open a mailbox it may have new mail in it and you will not get a call on this object. The reason is that the RECENT message to the mailbox is generated before the mailbox object is visible outside the Connection object it lives in. Note: When we call the action object you pass in to here, we supply an Integer (not an int) which has the value of number of messages which are new.

Parameters:

AsynchronousAction - a AsynchAction object to invoke on recent messages

  public void setExpungeAction(AsynchronousAction a)

This function sets the Aysnch.Action object which is associated with EXPUNGE messages. This indicates the messages are getting deleted by the server. As soon as a message is deleted, all higher number messages need to have their message numbers decremented by one. See RFC 1720 for more information on this. Also, by the time you get the expunge message the toolkit has already removed the message from its data structures so you can't FETCH() it or getData() it. It also has already renumbered all messages with higher numbers if you try to access them. The parameter supplied to your function is an Integer ( not an int ) which is the message number that has been expunged. It would probably behoove programmers using this API to simply do all message deletion processing in this callback. Since you get one of these for each deletion, it just makes life easy.

Parameters:

AsynchronousAction - a AsynchAction object to invoke on expunge messages

All Packages  Class Hierarchy  This Package  Previous  Next  Index