folder.java

java Email you can use it to send email to others

     *
     * @param msgs	fetch items for these messages
     * @param fp	the FetchProfile
     * @exception	IllegalStateException if this folder is not opened
     * @exception	MessagingException.
     */
    public void fetch(Message[] msgs, FetchProfile fp)
			throws MessagingException {
	return;
    }

    /**
     * Set the specified flags on the messages specified in the array.
     * This will result in appropriate MessageChangedEvents being
     * delivered to any MessageChangedListener registered on this
     * Message's containing folder. <p>
     *
     * Note that the specified Message objects <strong>must</strong> 
     * belong to this folder. Certain Folder implementations can
     * optimize the operation of setting Flags for a group of messages,
     * so clients might want to use this method, rather than invoking
     * <code>Message.setFlags</code> for each Message. <p>
     *
     * This implementation degenerates to invoking <code>setFlags()</code>
     * on each Message object. Specific Folder implementations that can 
     * optimize this case should do so. 
     * Also, an implementation must not abort the operation if a Message 
     * in the array turns out to be an expunged Message.
     *
     * @param msgs	the array of message objects
     * @param flag	Flags object containing the flags to be set
     * @param value	set the flags to this boolean value
     * @exception	IllegalStateException if this folder is not opened
     *			or if it has been opened READ_ONLY.
     * @exception 	MessagingException
     * @see		Message#setFlags
     * @see		javax.mail.event.MessageChangedEvent
     */
    public synchronized void setFlags(Message[] msgs,
			Flags flag, boolean value) throws  MessagingException {
	for (int i = 0; i < msgs.length; i++) {
	    try {
		msgs[i].setFlags(flag, value);
	    } catch (MessageRemovedException me) {
		// This message is expunged, skip 
	    }
	}
    }

    /**
     * Set the specified flags on the messages numbered from start
     * through end, both start and end inclusive. Note that message 
     * numbers start at 1, not 0.
     * This will result in appropriate MessageChangedEvents being
     * delivered to any MessageChangedListener registered on this
     * Message's containing folder. <p>
     *
     * Certain Folder implementations can
     * optimize the operation of setting Flags for a group of messages,
     * so clients might want to use this method, rather than invoking
     * <code>Message.setFlags</code> for each Message. <p>
     *
     * The default implementation uses <code>getMessage(int)</code> to
     * get each <code>Message</code> object and then invokes
     * <code>setFlags</code> on that object to set the flags.
     * Specific Folder implementations that can optimize this case should do so.
     * Also, an implementation must not abort the operation if a message 
     * number refers to an expunged message.
     *
     * @param start	the number of the first message
     * @param end	the number of the last message
     * @param flag	Flags object containing the flags to be set
     * @param value	set the flags to this boolean value
     * @exception	IllegalStateException if this folder is not opened
     *			or if it has been opened READ_ONLY.
     * @exception	IndexOutOfBoundsException if the start or end
     *			message numbers are out of range.
     * @exception 	MessagingException
     * @see		Message#setFlags
     * @see		javax.mail.event.MessageChangedEvent
     */
    public synchronized void setFlags(int start, int end,
			Flags flag, boolean value) throws MessagingException {
	for (int i = start; i <= end; i++) {
	    try {
		Message msg = getMessage(i);
		msg.setFlags(flag, value);
	    } catch (MessageRemovedException me) {
		// This message is expunged, skip 
	    }
	}
    }

    /**
     * Set the specified flags on the messages whose message numbers
     * are in the array.
     * This will result in appropriate MessageChangedEvents being
     * delivered to any MessageChangedListener registered on this
     * Message's containing folder. <p>
     *
     * Certain Folder implementations can
     * optimize the operation of setting Flags for a group of messages,
     * so clients might want to use this method, rather than invoking
     * <code>Message.setFlags</code> for each Message. <p>
     *
     * The default implementation uses <code>getMessage(int)</code> to
     * get each <code>Message</code> object and then invokes
     * <code>setFlags</code> on that object to set the flags.
     * Specific Folder implementations that can optimize this case should do so.
     * Also, an implementation must not abort the operation if a message 
     * number refers to an expunged message.
     *
     * @param msgnums	the array of message numbers
     * @param flag	Flags object containing the flags to be set
     * @param value	set the flags to this boolean value
     * @exception	IllegalStateException if this folder is not opened
     *			or if it has been opened READ_ONLY.
     * @exception	IndexOutOfBoundsException if any message number
     *			in the given array is out of range.
     * @exception 	MessagingException
     * @see		Message#setFlags
     * @see		javax.mail.event.MessageChangedEvent
     */
    public synchronized void setFlags(int[] msgnums,
			Flags flag, boolean value) throws MessagingException {
	for (int i = 0; i < msgnums.length; i++) {
	    try {
		Message msg = getMessage(msgnums[i]);
		msg.setFlags(flag, value);
	    } catch (MessageRemovedException me) {
		// This message is expunged, skip 
	    }
	}
    }

    /**
     * Copy the specified Messages from this Folder into another 
     * Folder. This operation appends these Messages to the 
     * destination Folder. The destination Folder does not have to 
     * be opened.  An appropriate MessageCountEvent 
     * is delivered to any MessageCountListener registered on the 
     * destination folder when the messages arrive in the folder. <p>
     *
     * Note that the specified Message objects <strong>must</strong> 
     * belong to this folder. Folder implementations might be able
     * to optimize this method by doing server-side copies. <p>
     *
     * This implementation just invokes <code>appendMessages()</code>
     * on the destination folder to append the given Messages. Specific
     * folder implementations that support server-side copies should
     * do so, if the destination folder's Store is the same as this
     * folder's Store. 
     * Also, an implementation must not abort the operation if a 
     * Message in the array turns out to be an expunged Message.
     *
     * @param msgs	the array of message objects
     * @param folder	the folder to copy the messages to
     * @exception	FolderNotFoundException if the destination
     *			folder does not exist.
     * @exception	IllegalStateException if this folder is not opened.
     * @exception	MessagingException
     * @see		#appendMessages
     */
    public void copyMessages(Message[] msgs, Folder folder)
				throws MessagingException {
	if (!folder.exists())
	    throw new FolderNotFoundException(
			folder.getFullName() + " does not exist",
			folder);

	folder.appendMessages(msgs);
    }

    /**
     * Expunge (permanently remove) messages marked DELETED. Returns an
     * array containing the expunged message objects.  The
     * <code>getMessageNumber</code> method
     * on each of these message objects returns that Message's original
     * (that is, prior to the expunge) sequence number. A MessageCountEvent 
     * containing the expunged messages is delivered to any 
     * MessageCountListeners registered on the folder. <p>
     *
     * Expunge causes the renumbering of Message objects subsequent to
     * the expunged messages. Clients that use message numbers as 
     * references to messages should be aware of this and should be 
     * prepared to deal with the situation (probably by flushing out 
     * existing message number caches and reloading them). Because of 
     * this complexity, it is better for clients to use Message objects
     * as references to messages, rather than message numbers. Any 
     * expunged Messages objects still have to be pruned, but other 
     * Messages in that folder are not affected by the expunge. <p>
     *
     * After a message is expunged, only the <code>isExpunged</code> and 
     * <code>getMessageNumber</code> methods are still valid on the
     * corresponding Message object; other methods may throw
     * <code>MessageRemovedException</code>
     *
     * @return		array of expunged Message objects
     * @exception	FolderNotFoundException if this folder does not
     *			exist
     * @exception	IllegalStateException if this folder is not opened.
     * @exception       MessagingException
     * @see		Message#isExpunged
     * @see		javax.mail.event.MessageCountEvent
     */
    public abstract Message[] expunge() throws MessagingException;

    /**
     * Search this Folder for messages matching the specified
     * search criterion. Returns an array containing the matching
     * messages . Returns an empty array if no matches were found. <p>
     *
     * This implementation invokes 
     * <code>search(term, getMessages())</code>, to apply the search 
     * over all the messages in this folder. Providers that can implement
     * server-side searching might want to override this method to provide
     * a more efficient implementation.
     *
     * @param term	the search criterion
     * @return 		array of matching messages 
     * @exception       javax.mail.search.SearchException if the search 
     *			term is too complex for the implementation to handle.
     * @exception	FolderNotFoundException if this folder does 
     *			not exist.
     * @exception	IllegalStateException if this folder is not opened.
     * @exception       MessagingException
     * @see		javax.mail.search.SearchTerm
     */
    public Message[] search(SearchTerm term) throws MessagingException {
	return search(term, getMessages());
    }

    /**
     * Search the given array of messages for those that match the 
     * specified search criterion. Returns an array containing the 
     * matching messages. Returns an empty array if no matches were 
     * found. <p>
     *
     * Note that the specified Message objects <strong>must</strong> 
     * belong to this folder. <p>
     *
     * This implementation iterates through the given array of messages,
     * and applies the search criterion on each message by calling
     * its <code>match()</code> method with the given term. The
     * messages that succeed in the match are returned. Providers
     * that can implement server-side searching might want to override
     * this method to provide a more efficient implementation. If the
     * search term is too complex or contains user-defined terms that
     * cannot be executed on the server, providers may elect to either
     * throw a SearchException or degenerate to client-side searching by
     * calling <code>super.search()</code> to invoke this implementation.
     *
     * @param term	the search criterion
     * @param msgs 	the messages to be searched
     * @return 		array of matching messages 
     * @exception       javax.mail.search.SearchException if the search 
     *			term is too complex for the implementation to handle.
     * @exception	IllegalStateException if this folder is not opened
     * @exception       MessagingException
     * @see		javax.mail.search.SearchTerm
     */
    public Message[] search(SearchTerm term, Message[] msgs)
				throws MessagingException {
	Vector matchedMsgs = new Vector();

	// Run thru the given messages
	for (int i = 0; i < msgs.length; i++) {
	    try {
		if (msgs[i].match(term)) // matched
		    matchedMsgs.addElement(msgs[i]); // add it
	    } catch(MessageRemovedException mrex) { }
	}

	Message[] m = new Message[matchedMsgs.size()];
	matchedMsgs.copyInto(m);
	return m;
    }

    /*
     * The set of listeners are stored in Vectors appropriate to their
     * type.  We mark all listener Vectors as "volatile" because, while
     * we initialize them inside this folder's synchronization lock,
     * they are accessed (checked for null) in the "notify" methods,
     * which can't be synchronized due to lock ordering constraints.
     * Since the listener fields (the handles on the Vector objects)
     * are only ever set, and are never cleared, we believe this is
     * safe.  The code that dispatches the notifications will either
     * see the null and assume there are no listeners or will see the
     * Vector and will process the listeners.  There's an inherent race
     * between adding a listener and notifying the listeners; the lack
     * of synchronization during notification does not make the race
     * condition significantly worse.  If one thread is setting a
     * listener at the "same" time an event is being dispatched, the
     * dispatch code might not see the listener right away.  The
     * dispatch code doesn't have to worry about the Vector handle
     * being set to null, and thus using an out-of-date set of
     * listeners, because we never set the field to null.
     */

    // Vector of connection listeners.
    private volatile Vector connectionListeners = null;

    /**
     * Add a listener for Connection events on this Folder. <p>
     *
     * The implementation provided here adds this listener
     * to an internal list of ConnectionListeners.
     *
     * @param l 	the Listener for Connection events
     * @see		javax.mail.event.ConnectionEvent
     */
    public synchronized void
    addConnectionListener(ConnectionListener l) { 
   	if (connectionListeners == null) 
	    connectionListeners = new Vector();
	connectionListeners.addElement(l);
    }

    /**
     * Remove a Connection event listener. <p>
     *
     * The implementation provided here removes this listener
     * from the internal list of ConnectionListeners.
     *
     * @param l 	the listener
     * @see		#addConnectionListener
     */
    public synchronized void
    removeConnectionListener(ConnectionListener l) { 
   	if (connectionListeners != null) 
	    connectionListeners.removeElement(l);
    }