package-summary.html

是MIDP 的API 查詢文件, 大家可以看一下裡面的index.html, 再用Package 或 Class 名字來查.

      <LI>
        The file extension of an application descriptor file is
        <CODE>jad</CODE>
      </LI>
      <LI>
        The MIME type of an application descriptor file is <BR>
        <CODE>text/vnd.sun.j2me.app-descriptor</CODE>.
      </LI>
    </UL>
    
    <P>
      A predefined set of attributes is
      specified to allow the application management software to identify,
      retrieve, and install the MIDlet(s). All attributes appearing in the
      descriptor file are made available to the MIDlet(s). The developer may
      use attributes not beginning with <CODE>MIDlet-</CODE> or
      <CODE>MicroEdition-</CODE> for
      application-specific purposes.
      Attribute names are case-sensitive and MUST match exactly.
      An attribute MUST NOT appear more than once within the manifest.
      If an attribute is duplicated the effect is unspecified.
      The MIDlet retrieves attributes by name by calling the
      <CODE>MIDlet.getAppProperty</CODE>  method.

</P>

    <P>
      The application descriptor MUST contain the following attributes:</P>
    <UL>
      <LI>
        MIDlet-Name</LI>
      <LI>
        MIDlet-Version</LI>
      <LI>
        MIDlet-Vendor</LI>
      <LI>
        MIDlet-Jar-URL</LI>
      <LI>
        MIDlet-Jar-Size</LI>
    </UL>
    <P>
      The application descriptor MAY contain:</P>
    <UL>
      <LI>
        MIDlet-&lt;n&gt; for each MIDlet</LI>
      <LI>
        MicroEdition-Profile</LI>
      <LI>
        MicroEdition-Configuration</LI>
      <LI>
        MIDlet-Description</LI>
      <LI>
        MIDlet-Icon</LI>
      <LI>
        MIDlet-Info-URL</LI>
      <LI>
        MIDlet-Data-Size</LI>
      <LI>
	MIDlet-Permissions </LI>
      <LI>
	MIDlet-Permissions-Opt </LI>
      <LI>
	MIDlet-Push-&lt;n&gt;</LI>
      <LI>
        MIDlet-Install-Notify</LI>
      <LI>
        MIDlet-Delete-Notify</LI>
      <LI>
        MIDlet-Delete-Confirm </LI>
      <LI>
        Any application-specific attributes that do not begin with
	<CODE>MIDlet-</CODE> or <CODE>MicroEdition-</CODE></LI>
    </UL>

    <P>
      The mandatory attributes MIDlet-Name, MIDlet-Version, and MIDlet-Vendor
      MUST be duplicated in the descriptor and manifest files since they
      uniquely identify the application. If they are
      not identical (not from the same application), then the JAR MUST NOT be
      installed. </P>
    <P>Duplication of other manifest attributes in the application
      descriptor is not required and their 
      values MAY differ even though both the manifest and descriptor files
      contain the same attribute for
      <A HREF="doc-files/Authorization.html#untrusted">untrusted</A>
      MIDlet suites. 
      If the MIDlet suite is not trusted the value from the descriptor
      file will override the value from the manifest file.
      If the MIDlet suite is
      <A HREF="doc-files/Authorization.html#trusted">trusted</A>
      then the values in the application descriptor 
      MUST be identical to the corresponding attribute values in the Manifest.
    </P>
    <P>
      MIDlets MUST NOT add any attributes to the manifest or the
      Application Descriptor that start with <CODE>MIDlet-</CODE> or
      <CODE>MicroEdition-</CODE> other than those defined in the relevant
      Configuration and Profiles (e.g. CLDC and MIDP) specifications.
      Unrecognized attributes MUST be ignored by the AMS.</P>
    <P>
      Generally speaking, the format of the application descriptor is a
      sequence of lines consisting of an attribute name followed by a colon,
      the value of the attribute, and a carriage return. White space is
      ignored before and after the value. The order of the attributes is
      arbitrary.</P>
    <P>
      The application descriptor MAY be encoded for transport or storage and
      MUST be converted to Unicode before parsing, using the rules below. For
      example, an ISO-8859-1 encoded file would need to be read through the
      equivalent of <CODE>java.io.InputStreamReader</CODE>
      with the appropriate encoding. The default character encoding for 
      transporting a descriptor is UTF-8. Descriptors retrieved via HTTP,
      if that is supported, SHOULD use the standard HTTP content negotiation
      mechanisms, such as the Content-Encoding header and the Content-Type
      charset parameter to convert the stream to UCS-2.</P>
    
    <EM>
      BNF for Parsing Application Descriptors</EM>
    <TABLE BORDER="2" width="400">
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <PRE><CODE>
 appldesc:  *attrline    
 attrline:  attrname &quot;:&quot; [WSP] attrvalue [WSP] newlines
 attrname:  1*&lt;any Unicode char except 
                 CTLs or separators&gt;    
 attrvalue: *valuechar | valuechar *(valuechar | WSP) valuechar    
 valuechar: &lt;any valid Unicode character, 
            excluding CTLS and WSP&gt;    
 newlines = 1*newline  ; allow blank lines to be ignored
 newline:   CR LF | LF 
   
 CR  = &lt;Unicode carriage return (U+000D)&gt;     
 LF  = &lt;Unicode linefeed (U+000A)&gt;     
 
 WSP:  1*( SP | HT )
 SP  = &lt;Unicode space (U+0020)&gt;
 HT  = &lt;Unicode horizontal-tab (U+0009)&gt;
 CTL = &lt;Unicode characters 
           U+0000 - U+001F and U+007F&gt;
 separators: &quot;(&quot; | &quot;)&quot; | &quot;&lt;&quot; |    
             &quot;&gt;&quot; | &quot;@&quot; |   
             &quot;,&quot; | &quot;;&quot; | &quot;:&quot; |    
             &quot;'&quot; | &lt;&quot;&gt;|    
             &quot;/&quot; | &quot;[&quot; | &quot;]&quot; |    
             &quot;?&quot; | &quot;=&quot; |        
             &quot;{&quot; | &quot;}&quot; | SP | HT            </CODE></PRE></TD>
      </TR>
    </TABLE>
    <P>
      For example, an application descriptor for a hypothetical suite of card
      games would look look like the following example:</P>
    <TABLE BORDER="2" width="400">
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
<PRE><CODE>
 MIDlet-Name: CardGames    
 MIDlet-Version: 1.1.9    
 MIDlet-Vendor: CardsRUS    
 MIDlet-1: Solitaire, /Solitare.png, com.cardsrus.org.Solitare     
 MIDlet-2: JacksWild, /JacksWild.png, com.cardsrus.org.JacksWild     
 MicroEdition-Profile: MIDP-2.0    
 MicroEdition-Configuration: CLDC-1.0    
 MIDlet-Description: Really cool card games    
 MIDlet-Jar-URL: http://www.cardsrus.com/games/cardgames.jar    
 MIDlet-Jar-Size: 7378    
 MIDlet-Data-Size: 256     </CODE></PRE>
        </TD>
      </TR>
    </TABLE>
    
    
    
    <H3>Application Lifecycle</H3>
    <P>
      Each MIDlet MUST extend the <CODE>MIDlet</CODE>
      class. The <CODE>MIDlet</CODE>
      class allows for the orderly starting, stopping, and cleanup of the
      MIDlet. The MIDlet can request the arguments from the application
      descriptor to communicate with the application management software. A
      MIDlet suite MUST NOT have a <CODE>public static void main()</CODE>
      method. If it exists, it MUST be ignored by the application management
      software. The application management software provides the initial
      class needed by the CLDC to start a MIDlet.</P>
    <P>
      When a MIDlet suite is installed on a device, its classes, resource
      files, arguments, and persistent storage are kept on the device and
      ready for use. The MIDlet(s) are available to the user via the device's
      application management software.</P>
    <P>
      When the MIDlet is run, an instance of the MIDlet's primary class is
      created using its public no-argument constructor, and the methods of
      the <CODE>MIDlet</CODE>
      are called to sequence the MIDlet through its various states. The
      MIDlet can either request changes in state or notify the application
      management software of state changes via the <CODE>MIDlet</CODE>
      methods. When the MIDlet is finished or terminated by the application
      management software, it is destroyed, and the resources it used can be
      reclaimed, including any objects it created and its classes. The
      MIDlet MUST NOT call <CODE>System.exit</CODE>
      , which will throw a <CODE>SecurityException</CODE>
      when called by a MIDlet.</P>
    <P>
      The normal states of Java classes are not affected by these classes as
      they are loaded. Referring to any class will cause it to be loaded, and
      the normal static initialization will occur.</P>
    <TABLE BORDER="2">
      <TR>
        <TH ROWSPAN="1" COLSPAN="1">
          Class in
          <CODE>javax.microedition.midlet</CODE>
        </TH>
        <TH ROWSPAN="1" COLSPAN="1">
          Description
        </TH>
      </TR>
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            <CODE>MIDlet</CODE>
          </P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            Extended by a MIDlet to allow the application management software to
            start, stop, and destroy it.</P>
        </TD>
      </TR>
      <TR>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            <CODE>MIDletStateChangeException</CODE>
          </P>
        </TD>
        <TD ROWSPAN="1" COLSPAN="1">
          <P>
            Thrown when the application cannot make the change requested.</P>
        </TD>
      </TR>
    </TABLE>
    <H3>MIDlet lifecycle</H3>
    
    <P align="LEFT">The <CODE>MIDlet</CODE> lifecycle defines the
      protocol between a <CODE>MIDlet</CODE> and its environment through
      the following:</P>

    <UL>
      <LI>
        <P>A simple well-defined state machine</P>
      </LI>

      <LI>
        <P>A concise definition of the MIDlet's states</P>
      </LI>

      <LI>
        <P>APIs to signal changes between the states</P>
      </LI>
    </UL>

    <H2>MIDlet Lifecycle Definitions</H2>

    <P>The following definitions are used in the <CODE>MIDlet</CODE>
      lifecycle:</P>

    <UL>
      <LI>
        <P><A name="appMgrDefined"></A>
          <B>application management software
            -</B> a part of the device's software operating environment that
          manages <CODE>MIDlets</CODE>. It maintains the MIDlet state
          and directs the <CODE>MIDlet</CODE>
          through state changes.</P>
      </LI>

      <LI>
        <P><CODE><B>MIDlet</B></CODE> - a MIDP application on the device.
          The <CODE>MIDlet</CODE> can signal the application management
          software about whether is it wants to run or has completed. A
          <CODE>MIDlet</CODE> has no knowledge of other <CODE>MIDlet</CODE>s
          through the <CODE>MIDlet</CODE> API.</P>
      </LI>

      <LI>
        <P><B><CODE>MIDlet</CODE> States</B> - the states a 
          <CODE>MIDlet</CODE> can have are defined by the transitions allowable
          through the <CODE>MIDlet</CODE> interface. More specific
          application states are known only to the application.</P>
      </LI>
    </UL>

    <H2>MIDlet States</H2>

    <P>The <CODE>MIDlet</CODE> state machine is designed to ensure that
      the behavior of an application is consistent and as close as
      possible to what device manufactures and users expect,
      specifically:</P>

    <UL>
      <LI>
        <P>The perceived startup latency of an application SHOULD be very
          short.</P>
      </LI>

      <LI>
        <P>It SHOULD be possible to put an application into a state where
          it is not active.</P>
      </LI>

      <LI>
        <P>It SHOULD be possible to destroy an application at any time.</P>
      </LI>
    </UL>

    <P style="margin-bottom: 0in">The valid states for
      <CODE>MIDlet</CODE>s are:</P>

    <TABLE width="100%" border="2" cellpadding="2" cellspacing="3">
     <TR>
        <TH width="20%">
          State Name
        </TH>
        <TH width="80%">
          Description
        </TH>
      </TR>

      <TR>
        <TD width="20%">
          <P>Paused</P>
        </TD>
        <TD width="80%">
          <P>The <CODE>MIDlet</CODE> is initialized and is quiescent. It
            SHOULD not be holding or using any shared resources. This state is
            entered:</P>

          <UL>
            <LI>
              <P>After the <CODE>MIDlet</CODE> has been created using