folder.html

来自「SUN公司官方J2EE中文帮助文档 应该不错 有兴趣的下来看看 html格式的」· HTML 代码 · 共 1,389 行 · 第 1/5 页

 <code>exists()</code> method on a Folder indicates whether it really
 exists on the Store. <p>

 In some Stores, name can be an absolute path if it starts with the
 hierarchy delimiter.  Otherwise, it is interpreted relative to
 this Folder. <p>

 Folder objects are not cached by the Store, so invoking this
 method on the same name multiple times will return that many
 distinct Folder objects. <p>

 This method can be invoked on a closed Folder.<DD><DL>
<DT><B>Parameters:</B><DD><CODE>name</CODE> - name of the Folder<DT><B>Returns:</B><DD>Folder object<DT><B>Throws:</B><DD><CODE><A HREF="../../javax/mail/MessagingException.html">MessagingException</A></CODE> - &nbsp;</DL>
</DD>
</DL>
<HR>

<A NAME="delete(boolean)"><!-- --></A><H3>
delete</H3>
<PRE>
public abstract boolean <B>delete</B>(boolean&nbsp;recurse)
                        throws <A HREF="../../javax/mail/MessagingException.html">MessagingException</A></PRE>
<DL>
<DD>Delete this Folder. This method will succeed only on a closed
 Folder. <p>

 The <code>recurse</code> flag controls whether the deletion affects
 subfolders or not. If true, all subfolders are deleted, then this
 folder itself is deleted. If false, the behaviour is dependent on
 the folder type and is elaborated below: <p>

 <ul>
 <li>
 The folder can contain only messages: (type == HOLDS_MESSAGES).
 <br>
 All messages within the folder are removed. The folder 
 itself is then removed. An appropriate FolderEvent is generated by 
 the Store and this folder. <p>

 <li>
 The folder can contain only subfolders: (type == HOLDS_FOLDERS).
 <br>
 If this folder is empty (does not contain any 
 subfolders at all), it is removed. An appropriate FolderEvent is 
 generated by the Store and this folder.<br>
 If this folder contains any subfolders, the delete fails 
 and returns false. <p>

 <li>
 The folder can contain subfolders as well as messages: <br>
 If the folder is empty (no messages or subfolders), it
 is removed. If the folder contains no subfolders, but only messages,
 then all messages are removed. The folder itself is then removed.
 In both the above cases, an appropriate FolderEvent is
 generated by the Store and this folder. <p>

 If the folder contains subfolders there are 3 possible
 choices an implementation is free to do: <p>
 
  <ol>
   <li> The operation fails, irrespective of whether this folder
 contains messages or not. Some implementations might elect to go
 with this simple approach. The delete() method returns false.

   <li> Any messages within the folder are removed. Subfolders
 are not removed. The folder itself is not removed or affected
 in any manner. The delete() method returns true. And the 
 exists() method on this folder will return true indicating that
 this folder still exists. <br>
 An appropriate FolderEvent is generated by the Store and this folder.

   <li> Any messages within the folder are removed. Subfolders are
 not removed. The folder itself changes its type from 
 HOLDS_FOLDERS | HOLDS_MESSAGES to HOLDS_FOLDERS. Thus new 
 messages cannot be added to this folder, but new subfolders can
 be created underneath. The delete() method returns true indicating
 success. The exists() method on this folder will return true
 indicating that this folder still exists. <br>
 An appropriate FolderEvent is generated by the Store and this folder.
 </ol>
 </ul><DD><DL>
<DT><B>Returns:</B><DD>true if the Folder is deleted successfully<DT><B>Throws:</B><DD><CODE><A HREF="../../javax/mail/FolderNotFoundException.html">FolderNotFoundException</A></CODE> - if this folder does 
			not exist<DD><CODE>java.lang.IllegalStateException</CODE> - if this folder is not in 
			the closed state.<DD><CODE><A HREF="../../javax/mail/MessagingException.html">MessagingException</A></CODE> - &nbsp;<DT><B>See Also: </B><DD><A HREF="../../javax/mail/event/FolderEvent.html"><CODE>FolderEvent</CODE></A></DL>
</DD>
</DL>
<HR>

<A NAME="renameTo(javax.mail.Folder)"><!-- --></A><H3>
renameTo</H3>
<PRE>
public abstract boolean <B>renameTo</B>(<A HREF="../../javax/mail/Folder.html">Folder</A>&nbsp;f)
                          throws <A HREF="../../javax/mail/MessagingException.html">MessagingException</A></PRE>
<DL>
<DD>Rename this Folder. This method will succeed only on a closed
 Folder. <p>

 If the rename is successful, a RENAMED FolderEvent is delivered
 to FolderListeners registered on this folder and its containing
 Store.<DD><DL>
<DT><B>Parameters:</B><DD><CODE>f</CODE> - a folder representing the new name for this Folder<DT><B>Returns:</B><DD>true if the Folder is renamed successfully<DT><B>Throws:</B><DD><CODE><A HREF="../../javax/mail/FolderNotFoundException.html">FolderNotFoundException</A></CODE> - if this folder does 
			not exist<DD><CODE>java.lang.IllegalStateException</CODE> - if this folder is not in 
			the closed state.<DD><CODE><A HREF="../../javax/mail/MessagingException.html">MessagingException</A></CODE> - &nbsp;<DT><B>See Also: </B><DD><A HREF="../../javax/mail/event/FolderEvent.html"><CODE>FolderEvent</CODE></A></DL>
</DD>
</DL>
<HR>

<A NAME="open(int)"><!-- --></A><H3>
open</H3>
<PRE>
public abstract void <B>open</B>(int&nbsp;mode)
                   throws <A HREF="../../javax/mail/MessagingException.html">MessagingException</A></PRE>
<DL>
<DD>Open this Folder. This method is valid only on Folders that
 can contain Messages and that are closed. <p>

 If this folder is opened successfully, an OPENED ConnectionEvent
 is delivered to any ConnectionListeners registered on this 
 Folder. <p>

 The effect of opening multiple connections to the same folder
 on a specifc Store is implementation dependent. Some implementations
 allow multiple readers, but only one writer. Others allow
 multiple writers as well as readers.<DD><DL>
<DT><B>Parameters:</B><DD><CODE>mode</CODE> - open the Folder READ_ONLY or READ_WRITE<DT><B>Throws:</B><DD><CODE><A HREF="../../javax/mail/FolderNotFoundException.html">FolderNotFoundException</A></CODE> - if this folder does 
			not exist.<DD><CODE>java.lang.IllegalStateException</CODE> - if this folder is not in 
			the closed state.<DD><CODE><A HREF="../../javax/mail/MessagingException.html">MessagingException</A></CODE> - &nbsp;<DT><B>See Also: </B><DD><A HREF="../../javax/mail/Folder.html#READ_ONLY"><CODE>READ_ONLY</CODE></A>, 
<A HREF="../../javax/mail/Folder.html#READ_WRITE"><CODE>READ_WRITE</CODE></A>, 
<A HREF="../../javax/mail/Folder.html#getType()"><CODE>getType()</CODE></A>, 
<A HREF="../../javax/mail/event/ConnectionEvent.html"><CODE>ConnectionEvent</CODE></A></DL>
</DD>
</DL>
<HR>

<A NAME="close(boolean)"><!-- --></A><H3>
close</H3>
<PRE>
public abstract void <B>close</B>(boolean&nbsp;expunge)
                    throws <A HREF="../../javax/mail/MessagingException.html">MessagingException</A></PRE>
<DL>
<DD>Close this Folder. This method is valid only on open Folders. <p>

 A CLOSED ConnectionEvent is delivered to any ConnectionListeners
 registered on this Folder. Note that the folder is closed even
 if this method terminates abnormally by throwing a
 MessagingException.<DD><DL>
<DT><B>Parameters:</B><DD><CODE>expunge</CODE> - expunges all deleted messages if this flag is true<DT><B>Throws:</B><DD><CODE>java.lang.IllegalStateException</CODE> - if this folder is not opened<DD><CODE><A HREF="../../javax/mail/MessagingException.html">MessagingException</A></CODE> - &nbsp;<DT><B>See Also: </B><DD><A HREF="../../javax/mail/event/ConnectionEvent.html"><CODE>ConnectionEvent</CODE></A></DL>
</DD>
</DL>
<HR>

<A NAME="isOpen()"><!-- --></A><H3>
isOpen</H3>
<PRE>
public abstract boolean <B>isOpen</B>()</PRE>
<DL>
<DD>Indicates whether this Folder is in the 'open' state.<DD><DL>
<DT><B>Returns:</B><DD>true if this Folder is in the 'open' state.</DL>
</DD>
</DL>
<HR>

<A NAME="getMode()"><!-- --></A><H3>
getMode</H3>
<PRE>
public int <B>getMode</B>()</PRE>
<DL>
<DD>Return the open mode of this folder.  Returns
 <code>Folder.READ_ONLY</code>, <code>Folder.READ_WRITE</code>,
 or -1 if the open mode is not known (usually only because an older
 <code>Folder</code> provider has not been updated to use this new
 method).<DD><DL>
<DT><B>Returns:</B><DD>the open mode of this folder<DT><B>Throws:</B><DD><CODE>java.lang.IllegalStateException</CODE> - if this folder is not opened<DT><B>Since: </B><DD>JavaMail 1.1</DD>
</DL>
</DD>
</DL>
<HR>

<A NAME="getPermanentFlags()"><!-- --></A><H3>
getPermanentFlags</H3>
<PRE>
public abstract <A HREF="../../javax/mail/Flags.html">Flags</A> <B>getPermanentFlags</B>()</PRE>
<DL>
<DD>Get the permanent flags supported by this Folder. Returns a Flags
 object that contains all the flags supported. <p>

 The special flag <code>Flags.USER </code> indicates that this Folder
 supports arbitrary user-defined flags. <p>

 The supported permanent flags for a folder may not be available
 until the folder is opened.<DD><DL>
<DT><B>Returns:</B><DD>permanent flags, or null if not known</DL>
</DD>
</DL>
<HR>

<A NAME="getMessageCount()"><!-- --></A><H3>
getMessageCount</H3>
<PRE>
public abstract int <B>getMessageCount</B>()
                             throws <A HREF="../../javax/mail/MessagingException.html">MessagingException</A></PRE>
<DL>
<DD>Get total number of messages in this Folder. <p>

 This method can be invoked on a closed folder. However, note
 that for some folder implementations, getting the total message
 count can be an expensive operation involving actually opening 
 the folder. In such cases, a provider can choose not to support 
 this functionality in the closed state, in which case this method
 must return -1. <p>

 Clients invoking this method on a closed folder must be aware
 that this is a potentially expensive operation. Clients must
 also be prepared to handle a return value of -1 in this case.<DD><DL>
<DT><B>Returns:</B><DD>total number of messages. -1 may be returned
			by certain implementations if this method is
			invoked on a closed folder.<DT><B>Throws:</B><DD><CODE><A HREF="../../javax/mail/FolderNotFoundException.html">FolderNotFoundException</A></CODE> - if this folder does 
			not exist.<DD><CODE><A HREF="../../javax/mail/MessagingException.html">MessagingException</A></CODE> - &nbsp;</DL>
</DD>
</DL>
<HR>

<A NAME="getNewMessageCount()"><!-- --></A><H3>
getNewMessageCount</H3>
<PRE>
public int <B>getNewMessageCount</B>()
                       throws <A HREF="../../javax/mail/MessagingException.html">MessagingException</A></PRE>
<DL>
<DD>Get the number of new messages in this Folder. <p>

 This method can be invoked on a closed folder. However, note
 that for some folder implementations, getting the new message
 count can be an expensive operation involving actually opening 
 the folder. In such cases, a provider can choose not to support 
 this functionality in the closed state, in which case this method
 must return -1. <p>

 Clients invoking this method on a closed folder must be aware
 that this is a potentially expensive operation. Clients must
 also be prepared to handle a return value of -1 in this case. <p>

 This implementation returns -1 if this folder is closed. Else
 this implementation gets each Message in the folder using
 <code>getMessage(int)</code> and checks whether its
 <code>RECENT</code> flag is set. The total number of messages
 that have this flag set is returned.<DD><DL>
<DT><B>Returns:</B><DD>number of new messages. -1 may be returned
			by certain implementations if this method is
			invoked on a closed folder.<DT><B>Throws:</B><DD><CODE><A HREF="../../javax/mail/FolderNotFoundException.html">FolderNotFoundException</A></CODE> - if this folder does 
			not exist.<DD><CODE><A HREF="../../javax/mail/MessagingException.html">MessagingException</A></CODE> - &nbsp;</DL>
</DD>
</DL>
<HR>

<A NAME="getUnreadMessageCount()"><!-- --></A><H3>
getUnreadMessageCount</H3>
<PRE>
public int <B>getUnreadMessageCount</B>()
                          throws <A HREF="../../javax/mail/MessagingException.html">MessagingException</A></PRE>
<DL>
<DD>Get the total number of unread messages in this Folder. <p>

 This method can be invoked on a closed folder. However, note
 that for some folder implementations, getting the unread message
 count can be an expensive operation involving actually opening 
 the folder. In such cases, a provider can choose not to support 
 this functionality in the closed state, in which case this method
 must return -1. <p>

 Clients invoking this method on a closed folder must be aware
 that this is a potentially expensive operation. Clients must
 also be prepared to handle a return value of -1 in this case. <p>

 This implementation returns -1 if this folder is closed. Else
 this implementation gets each Message in the folder using
 <code>getMessage(int)</code> and checks whether its
 <code>SEEN</code> flag is set. The tota