javamail-1 4 1docsproviders

1、1JavaMailTM Guide forService ProvidersSun Microsystems, Inc.901 San Antonio Road Palo Alto, CA 94303 USARevision 01, August 1998650 960-1300fax 650 969-9131JavaMail Guide for Service ProvidersCopyright 1998 Sun Microsystems, Inc., 901 San Antonio Road, PaloAlto, California 94303 U.S.A. All rights re

2、served.Copyright 1998 Sun Microsystems, Inc., 901 San Antonio Road, PaloAlto, Californie 94303 Etats-Unis. Tous droits rservs.This product or documentation is protected by copyright anddistributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product o

3、r documentation may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. Third-party software, including font technology, is copyrighted and licensed from Sun suppliers.Ce produit ou document est protg par un copyright et distribuavec des licen

4、ces qui en restreignent lutilisation, la copie, la distribution, et la dcompilation. Aucune partie de ce produit ou document ne peut tre reproduite sous aucune forme, par quelque moyen que ce soit, sans lautorisation pralable et crite de Sun et de ses bailleurs de licence, sil y en a. Le logiciel dt

5、enu par des tiers, et qui comprend la technologie relative aux polices de caractres, est protg par un copyright et licenci par des fournisseurs de Sun.Sun, Sun Microsystems, the Sun logo, Java, JavaSoft, JavaMail,JavaBeans, JDK, and Solaris are trademarks or registered trademarks of Sun Microsystems

6、, Inc. in the U.S. and other countries.Sun, Sun Microsystems, le logo Sun, Solaris, Java, JavaSoft, JavaMail,JavaBeans, JDK sont des marques de fabrique ou des marques dposes de Sun Microsystems, Inc. aux Etats-Unis et dans dautres pays. Linterface dutilisation graphique OPEN LOOK et Sun a t dvelopp

7、e par Sun Microsystems, Inc. pour ses utilisateurs et licencis. Sun reconnat les efforts de pionniers de Xerox pour la recherche et le dveloppement du concept des interfacesdutilisation visuelle ou graphique pour lindustrie delinformatique. Sun dtient une licence non exclusive de Xerox sur linterfac

8、e dutilisation graphique Xerox, cette licence couvrant galement les licencis de Sun qui mettent en place linterfacedutilisation graphique OPEN LOOK et qui en outre se conforment aux licences crites de Sun. Laccord du gouvernement amricain est requis avant lexportation du produit.The OPEN LOOK and Su

9、n Graphical User Interface wasdeveloped by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to

10、the Xerox Graphical User Interface, which license also covers Suns licensees who implement OPEN LOOK GUIs and otherwise comply with Suns written license agreements.U.S. Government approval required when exporting the product. Use, duplication, or disclosure by the U.S. Govt is subject to restriction

11、s of FAR 52.227-14(g)(2)(6 / 87) and FAR 52.227-19(6 / 87), or DFAR 252.227-7015 (b)(6 / 95) and DFAR 227.7202-3(a)DOCUMENTATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, ANY KIND OF IMPLIED OR EXPRESS WARRANTY OF NON-INFRINGEMENT OR T

12、HE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.LA DOCUMENTATION EST FOURNIE “EN LETAT” ET TOUTESAUTRES CONDITIONS, DCLARATIONS ET GARANTIES EXPRESSES OU TACITES SONT FORMELLEMENT EXCLUES DANS LA MESURE AUTORISE PAR LA LOI APPLICABLE, Y COMPRIS NOTAMMENT TOUTE GARANTIE I

13、MPLICITE RELATIVE LA QUALIT MARCHANDE, LAPTITUDE UNE UTILISATION PARTICULRE OU LABSENCE DE CONTREFAON.Copyright 1998 Sun Microsystems, Inc. All rights reserved. Use issubject to license terms. Third-party software, including font technology, is copyrighted and licensed from Sun suppliers. Sun, Sun M

14、icrosystems, the Sun Logo, Solaris, Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Use, duplication, or disclosure by the U.S. Govt is subject to restrictions of FAR 52.227-14(g)(2)(6 / 87) and FAR 52.227-19(6 / 87), or DFAR 252.227-7015 (b)(6

15、 / 95) and DFAR 227.7202-3(a)Copyright 1998 Sun Microsystems, Inc. Tous droits rservs.Distribu par des licences qui en restreignent lutilisation. Le logiciel dtenu par des tiers, et qui comprend la technologie relative aux polices de caractres, est protg par un copyright et licenci par des fournisse

16、urs de Sun. Sun, Sun Microsystems, le logo Sun, Solaris, Java sont des marques de fabrique ou des marques dposes de Sun Microsystems, Inc. aux Etats-Unis et dans dautres pays.PleaseRecycleAugust 1998iiiContentsChapter 1: Introduction 1Chapter 2: Messages 3The Structure of a Message 3 Simple Messages

17、 4Multipart Messages 4Messages and the JavaBeans Activation Framework 5 The DataSource 6The DataContentHandler 6Message Subclasses 7Creating a Message Subclass 7 Message Attributes 7 Setting Message Content 8Accessing Message Content 8 Creating a MimeMessage Subclass 9Creating the Subclass 9 Headers

18、 10Content12Special Cases: Protocols that Provide Preparsed Data13Chapter 3: Message Storage and Retrieval 15Store 15Authentication 15The protocolConnect Method 16 The connect Method 16Folder Retrieval 16Folders 17Folder Naming 18Folder State 18Messages Within a Folder 19 Getting Messages 20Searchin

19、g Messages 21Getting Message Data in Bulk 22 Folder Management 23Appending and Copying Messages 23 Expunging Messages 23August 1998JavaMail Guide for Service ProvidersivContentsHandling Message Flags 24Chapter 4: Message Transport 25Transport 25The sendMessage Method 25 The protocolConnect MethodAdd

20、ress 2726Chapter 5: Events 29Chapter 6: Packaging31August 1998JavaMail Guide for Service Providers1Chapter 1:IntroductionJavaMail provides a common, uniform API for managing electronic mail. It allowsservice-providers to provide a standard interface to their standards-based or proprietary messaging

21、systems using the Java programming language. Using this API, applications access message stores, and compose and send messages.MailNetworkJavaMail ClientMail ServerFIGURE 1-1The JavaMail API is composed of a set of abstract classes that model the variouspieces of a typical mail system. These classes

22、 include,MessageAbstract class that represents an electronic mail message.JavaMail implements the RFC822 and MIME Internet messaging standards. TheMimeMessage class extends Message to represent a MIME-style email message.StoreAbstract class that represents a database of messages maintained by a mail

23、 server and grouped by owner. A Store uses a particular access protocol.FolderAbstract class that provides a way of hierarchically organizing messages. Folders can contain messages and other folders. A mail server provides each user with a default folder, and users can typically create and fill subf

24、olders.TransportAbstract class that represents a specific transport protocol. ATransport object uses a particular transport protocol to send a message.As a service provider, you implement abstract classes in terms of your specific protocol or system. For example, an IMAP provider implements the Java

25、Mail API using the IMAP4 protocol. Clients then use your implementation to manipulate their electronic mail.August 1998JavaMail Guide for Service Providers2Chapter 1: IntroductionFIGURE 1-2 shows a client using an IMAP4 implementation to read mail, and anSMTP implementation to send mail. (They can b

26、e from the same or different vendors.)Mail ServerDestinationIMAPSMTPFIGURE 1-2This Service Providers Guide shows you how to develop and package a JavaMailservice provider for your clients. It is meant to be used in conjunction with the Javadoc provided with the JavaMail API and the JavaMail API Spec

27、ification.This guide covers: Creating messages Storing and retrieving messages Sending a message Communicating with a client (for example, notifying the client of new mail) Packaging your implementationThe descriptions of the first three tasks show how to subclass the appropriate abstract classes an

28、d implement their abstract methods. In addition, the task descriptions point out the methods that have default implementations that you might choose to override for the sake of efficiency.JavaMail Guide for Service ProvidersAugust 1998JavaMail ClientCalls forCalls forsending mailreading mailImplemen

29、tation:Implementation:SMTPTransport.IMAPStore,IMAPFoldeSrM.TPAbstract ClassesTransport,Store, Folder.3Chapter 2:MessagesMessages are central to any electronic mail system. This chapter discusses how toimplement them for your provider.If your provider allows only for the common case of creating and s

30、ending MIME style messages, then your provider can use the pre-written JavaMail message implementation: the ernet.MimeMessage class. Implementations that furnish a protocol like SMTP fall into this category.If your implementation does not fall into the previous category, you will have

31、to implement your own Message subclass. This chapter Explains the structure of a Message object Explains how Message objects use the JavaBeansTM Activation Framework Shows you how to develop a Message subclassThe Structure of a MessageThe Message class models an electronic mail message. It is an abs

32、tract class that implements the Part interface.The Message class defines a set of attributes and content for an electronic mail message. The attributes, which are name-value pairs, specify addressing information and define the structure of the messages content (its content type). Messages can contai

33、n a single content object or, indirectly, multiple content objects. In either case, the content is held by a DataHandler object.August 1998JavaMail Guide for Service Providers4Chapter 2: MessagesThe Structure of a MessageSimple MessagesA simple message has a single content object, which is wrapped b

34、y a DataHandlerobject. FIGURE 2-1 shows the structure of a Messageobject:FIGURE 2-1Structure of a Simple MessageMultipart MessagesIn addition to the simple structure shown in FIGURE 2-1, messages can also contain multiple content objects. In this case the DataHandler object contains a Multipart obje

35、ct, instead of merely a a single block of content data.A Multipart object is a container of BodyPart objects. The structure of a BodyPart object is similar to the structure of a Message object, because they both implement the Part interface.Each BodyPart object contains attributes and content, but t

36、he attributes of a Bodypart object are limited to those defined by the Part interface. An important attribute is the content-type of this part of the message content. The content of a BodyPart object is a DataHandler that contains either data or another Multipart object. FIGURE 2-2 on page 5 shows t

37、his structure.JavaMail Guide for Service ProvidersAugust 1998Message ClassContent BodyDataHandler ObjectContains data that conforms to the Content-Type attributeHeader AttributesAttributes, such asContent-Type.Chapter 2: MessagesMessages and the JavaBeans Activation Framework5FIGURE 2-2Structure of

38、a Message with Multiple Content TypesMessages and theJavaBeans Activation FrameworkAs shown in FIGURE 2-1 on page 4, the content of a message is represented by a DataHandler object. The DataHandler class is part of the JavaBeans Activation Framework (JAF). Documentation on the JAF can be obtained fr

39、om the world-wide web at/beans/glasgow/jaf.html.The DataHandler class provides a consistent interface to data, independent of its source and format. The data can be from message stores, local files, URLs or objects in the Java programming language.August 1998JavaMail Guide for Serv

40、ice ProvidersMessageContent BodyDataHandler ObjectContains a Multipart object instead of dataHeader AttributesMessage attributes, with a content type of Multipart.Multipart ObjectBodyPart ObjectA Multipart Message can hold more than one BodyPart Object.BodyPart ObjectContent BodyDataHandler ObjectCo

41、ntains either data, or another Multipart object.Header AttributesAttributes from thePart interface,such as this parts content type6Chapter 2: MessagesMessages and the JavaBeans Activation FrameworkThe DataSourceA DataHandler object accepts data in the form of an object in the Java programming langua

42、ge directly. For data from message stores, files or URLs, however, a DataHandler depends on objects that implement the DataSource interface to provide data access. A DataSource object provides access to data in the form of an input stream.The DataSource interface is also part of the JAF. JavaMail pr

43、ovides the following DataSource objects: javax.mail.MultipartDataSource ernet.MimePartDataSourceThe DataContentHandlerDataHandler objects return the content of a message as an object in the Java programming language. They use objects that implement the DataContentHandler interface to t

44、ranslate message content between the streams provided by DataSource objects and objects in the Java programming language. The getContent and writeTo methods of the text / plain DataContentHandler show this:public class text_plain implements DataContentHandler / This method creates a String from a “t

45、ext/plain”/ data sourcepublic Object getContent(DataSource dataSource) InputStream inputStream = dataSource.getInputStream(); ByteArrayOutputStream outputStream =new ByteArrayOutputStream();while (c = inputStream.read() != -1) outputStream.write(c)/ get the character set from the content-typeString

46、charset = getCharSet(dataSource.getContentType(); return new String(outputStream.toByteArray(), charset);/ This method creates a byte stream from a Stringpublic void writeTo(Object object, String type,OutputStream outputStream) OutputStreamWriter writer =new OutputStreamWriter(outputStream, getChars

47、et(type); String string = (String)object;writer.write(string, 0, string.length(); writer.flush();JavaMail Guide for Service ProvidersAugust 1998Chapter 2: MessagesMessage Subclasses7DataContentHandlers are also part of the JAF. The JavaMail implementation in the com.sun.mail.handlers package include

48、s DataContentHandlers for the following two MIME types: multipart/mixed(the name of the class is multipart_mixed) text/plain (the name of the class is text_plain)A DataHandler typically finds the correct DataContentHandler for a particular MIME type through the MailCap registry. (The client programm

49、er can also provide the correspondence programmatically.)Message SubclassesThe following factors determine the message class of your provider: If applications will use your provider for interacting with a non-MIME messaging system, create a subclass of the Message class (See “Creating a MessageSubcl

50、ass” on page 7.) If applications will use your provider to interact with a message store that supports MIME messages, create a subclass of the MimeMessage class. (See “Creating a MimeMessage Subclass” on page 9.) If applications will use your provider to send MIME messages then use theMimeMessage cl

51、ass without subclassing it.Creating a Message SubclassWhen you subclass the Message class, you must implement methods that manage attributes, that retrieve content, and that set content.Message AttributesYour implementation is expected to support the attributes in the Message class and its Part inte

52、rface by implementing their get and set methods. If your messaging system does not allow the modification of an attribute, have the method that sets it throw the IllegalWriteException.In addition to supporting the predefined attributes, you can also expose attributes specific to your implementation.

53、 To make a system-specific attribute available in your subclass, add a field that represents the attribute and provide accessor methods for it.August 1998JavaMail Guide for Service Providers8Chapter 2: MessagesMessage SubclassesSetting Message ContentThe Message class provides a number of abstract m

54、ethods for setting message content. These will be used by clients preparing an outgoing message.Some methods take message data directly, and expect your implementation to wrap the data in a DataHandler object:public void setContent(java.lang.Object obj,java.lang.String type) public void setText(java

55、.lang.String text)To wrap the data, use the DataHandler constructor that requires an object and a data type. You can then call the same method that clients call when they have wrapped their data in a DataHandler object themselves:public void setDataHandler(javax.activation.DataHandler dh)This method

56、 is abstract.Accessing Message ContentThe Message class provides three methods for getting the message content: public javax.activation.DataHandler getDataHandler() public java.lang.Object getContent() public java.io.InputStream getInputStream()They are used by clients to get a message from a folder

57、. To implement these methods:1. Optional: provide a cache for the DataHandler objectCaching the DataHandler can improve performance if it reduces the number of times you must access the store.public MyMessage extends Message / field for caching the data handlerprivate DataHandler dh;.2. Implement the abstract getDataHandler methodReturn the appropriate DataHandler object. For example:public MyMessage