Merge branch '1.0-local' into trunk-local

* 1.0-local:
  Disables serialization warnigs. Increases number of allowed warnings so that we can track the total number as it decreases.
  Adds class javadocs. Problem reported by Linus

build.xml

@@ -42,7 +42,7 @@
     <property name="inst.resrc" value="${sc.basedir}/resources/install"/>
     <property name="path" value="${lib}/native/windows;${system.PATH}"/>
     <property name='j2se_api' value='http://java.sun.com/j2se/1.5/docs/api' />
-    <property name='maxwarns' value='101' />
+    <property name='maxwarns' value='10000' />
 
     <!-- set the build label property and make it take the cc bild into account -->
     <condition property="build.label"
@@ -233,7 +233,7 @@
                 <src path="${src2}"/>
                 <include name="**/*.java" />
                 <exclude name="net/java/sip/communicator/launcher/*.java" />
-                <compilerarg line="-Xlint -Xmaxwarns ${maxwarns}"/>
+                <compilerarg line="-Xlint -Xlint:-serial -Xmaxwarns ${maxwarns}"/>
         </javac>
         <!--
             sc-launcher.jar needs to be compatible with 1.4 in order to enable

src/net/java/sip/communicator/service/protocol/OperationSetPresence.java

@@ -11,14 +11,15 @@
 import net.java.sip.communicator.service.protocol.event.*;
 
 /**
- * OperationSetPresence offers methods for
- * 
- * @todo Say that ContactList management is else where and Presence functions
- *       are here
- * @todo Say that presence implementations should not contain any persistent
- *       data of subscriptions
- * @todo say that this is not persistent and that persistent is elsewhere.
- * 
+ * OperationSetPresence offers methods that allow managing the presence status
+ * of the provider, and subscribing to that of our buddies (i.e. adding contacts
+ * to our contact list).
+ * <p>
+ * This operation set is meant to be implemented by all protocols that support
+ * presence, regardless of whether or not they can store contacts somewhere
+ * on the network. Operations that allow managing server stored contact lists
+ * are part of {@link OperationSetPersistentPresence}.
+ *
  * @author Emil Ivov
  */
 public interface OperationSetPresence
@@ -31,7 +32,7 @@ public interface OperationSetPresence
      * during its lifecycle, including those that would not be visible to others
      * (e.g. Initializing, Connecting, etc ..) and those that will be sent to
      * contacts/buddies (On-Line, Eager to chat, etc.).
-     * 
+     *
      * @return the PresenceStatus last published by this provider.
      */
     public PresenceStatus getPresenceStatus();
@@ -43,7 +44,7 @@ public interface OperationSetPresence
      * return right after being called and the caller should add itself as a
      * listener to this class in order to get notified when the state has
      * actually changed.
-     * 
+     *
      * @param status the PresenceStatus as returned by getRequestableStatusSet
      * @param statusMessage the message that should be set as the reason to
      *            enter that status
@@ -67,7 +68,7 @@ public void publishPresenceStatus(PresenceStatus status,
      * instances that users may request to enter. (e.g. a user may not request a
      * "Connecting..." state - it is a temporary state that the provider enters
      * while trying to enter the "Connected" state).
-     * 
+     *
      * @return Iterator a PresenceStatus array containing "enterable" status
      *         instances.
      */
@@ -80,12 +81,12 @@ public void publishPresenceStatus(PresenceStatus status,
      * plugins that may for some reason need to know the status of a particular
      * contact.
      * <p>
-     * 
+     *
      * @param contactIdentifier the identifier of the contact whose status we're
      *            interested in.
      * @return PresenceStatus the <tt>PresenceStatus</tt> of the specified
      *         <tt>contact</tt>
-     * 
+     *
      * @throws OperationFailedException with code NETWORK_FAILURE if retrieving
      *             the status fails due to errors experienced during network
      *             communication
@@ -110,7 +111,7 @@ public PresenceStatus queryContactStatus(String contactIdentifier)
      * This subscription is not going to be persistent (as opposed to
      * subscriptions added from the OperationSetPersistentPresence.subscribe()
      * method)
-     * 
+     *
      * @param contactIdentifier the identifier of the contact whose status
      *            updates we are subscribing for.
      *            <p>
@@ -128,10 +129,10 @@ public void subscribe(String contactIdentifier)
 
     /**
      * Removes a subscription for the presence status of the specified contact.
-     * 
+     *
      * @param contact the contact whose status updates we are unsubscribing
      *            from.
-     * 
+     *
      * @throws OperationFailedException with code NETWORK_FAILURE if
      *             unsubscribing fails due to errors experienced during network
      *             communication
@@ -148,7 +149,7 @@ public void unsubscribe(Contact contact)
     /**
      * Returns a reference to the contact with the specified ID in case we have
      * a subscription for it and null otherwise/
-     * 
+     *
      * @param contactID a String identifier of the contact which we're seeking a
      *            reference of.
      * @return a reference to the Contact with the specified <tt>contactID</tt>
@@ -160,7 +161,7 @@ public void unsubscribe(Contact contact)
      * Handler for incoming authorization requests. An authorization request
      * notifies the user that someone is trying to add her to their contact list
      * and requires her to approve or reject authorization for that action.
-     * 
+     *
      * @param handler an instance of an AuthorizationHandler for authorization
      *            requests coming from other users requesting permission add us
      *            to their contact list.
@@ -170,7 +171,7 @@ public void unsubscribe(Contact contact)
     /**
      * Adds a listener that would receive events upon changes of the provider
      * presence status.
-     * 
+     *
      * @param listener the listener to register for changes in our
      *            PresenceStatus.
      */
@@ -180,7 +181,7 @@ public void addProviderPresenceStatusListener(
     /**
      * Unregisters the specified listener so that it does not receive further
      * events upon changes in local presence status.
-     * 
+     *
      * @param listener ProviderPresenceStatusListener
      */
     public void removeProviderPresenceStatusListener(
@@ -194,7 +195,7 @@ public void removeProviderPresenceStatusListener(
      * receive updates for status changes for any contact and it is not
      * currently possible to register such contacts for a single contact or a
      * subset of contacts.
-     * 
+     *
      * @param listener the listener that would received presence status updates
      *            for contacts.
      */
@@ -204,7 +205,7 @@ public void addContactPresenceStatusListener(
     /**
      * Removes the specified listener so that it won't receive any further
      * updates on contact presence status changes
-     * 
+     *
      * @param listener the listener to remove.
      */
     public void removeContactPresenceStatusListener(
@@ -213,21 +214,21 @@ public void removeContactPresenceStatusListener(
     /**
      * Registers a listener that would get notifications any time a new
      * subscription was successfully added, has failed or was removed.
-     * 
+     *
      * @param listener the SubscriptionListener to register
      */
     public void addSubscriptionListener(SubscriptionListener listener);
 
     /**
      * Removes the specified subscription listener.
-     * 
+     *
      * @param listener the listener to remove.
      */
     public void removeSubscriptionListener(SubscriptionListener listener);
 
     /**
      * Returns the status message that was confirmed by the server
-     * 
+     *
      * @return the last status message that we have requested and the aim server
      *         has confirmed.
      */
@@ -240,12 +241,12 @@ public void removeContactPresenceStatusListener(
      * against the server. The protocol provider may will later try and resolve
      * the contact. When this happens the corresponding event would notify
      * interested subscription listeners.
-     * 
+     *
      * @param address an identifier of the contact that we'll be creating.
      * @param persistentData a String returned Contact's getPersistentData()
      *            method during a previous run and that has been persistently
      *            stored locally.
-     * 
+     *
      * @return the unresolved <tt>Contact</tt> created from the specified
      *         <tt>address</tt> and <tt>persistentData</tt>
      */