[sc1.0-cvs] CVS update: /sip-communicator-1-0-draft/src/net/java/sip/communicator/service/contactlist/

emcho at dev.java.net emcho at dev.java.net
Sun Feb 5 17:07:00 CET 2006


User: emcho   
Date: 2006/02/05 08:07:00

Log:
 Replaced <code> tags with <tt> in all javadocs

File Changes:

Directory: /sip-communicator-1-0-draft/src/net/java/sip/communicator/service/contactlist/
=========================================================================================

File [changed]: MetaContact.java
Url: https://sip-communicator-1-0-draft.dev.java.net/source/browse/sip-communicator-1-0-draft/src/net/java/sip/communicator/service/contactlist/MetaContact.java?r1=1.1&r2=1.2
Delta lines:  +55 -1
--------------------
--- MetaContact.java	3 Feb 2006 16:29:53 -0000	1.1
+++ MetaContact.java	5 Feb 2006 16:06:56 -0000	1.2
@@ -6,10 +6,64 @@
  */
 package net.java.sip.communicator.service.contactlist;
 
+
+import net.java.sip.communicator.service.protocol.*;
+import java.util.List;
+
 /**
- *
+ * A MetaContact is an abstraction used for merging mutltiple Contacts (most
+ * often) belonging to different <tt>ProtocolProvider</tt>s.
+ * <p>
+ * Instances of a MetaContact are readonly objects that cannot be modified
+ * directly but only through the corresponding MetaContactListService.
+ * <p>
  * @author Emil Ivov
  */
 public interface MetaContact
 {
+    /**
+     * Returns the default protocol specific <tt>Contact</tt> to use when
+     * communicating with this <tt>MetaContact</tt>.
+     * @return the default <tt>Contact</tt> to use when communicating with
+     * this <tt>MetaContact</tt>
+     */
+    public Contact getDefaultContact();
+
+    /**
+     * Returns a <tt>java.util.List</tt> with all protocol specific
+     * <tt>Contacts</tt> encapsulated by this <tt>MetaContact</tt>.
+     * @return a <tt>java.util.List</tt> containing all protocol specific
+     * <tt>Contact</tt>s that were registered as subcontacts for this
+     * <tt>MetaContact</tt>
+     */
+    public List getContacts();
+
+    /**
+     * Returns the number of protocol speciic <tt>Contact</tt>s that this
+     * <tt>MetaContact</tt> contains.
+     * @return an int indicating the number of protocol specific contacts merged
+     * in this <tt>MetaContact</tt>
+     */
+    public int getContactCount();
+
+    /**
+     * Returns a Contact, encapsulated by this MetaContact and coming from the
+     * specified ProtocolProviderService. If none of the contacts encapsulated
+     * by this MetaContact is originating from the specified provider then
+     * <tt>null</tt> is returned.
+     * <p>
+     * @param provider a reference to the <tt>ProtocolProviderService</tt>
+     * that we'd like to get a <tt>Contact</tt> for.
+     * @return a <tt>Contact</tt> encapsulated in this
+     * <tt>MetaContact</tt> and originating from the specified provider.
+     */
+    public Contact getContactForProvider(ProtocolProviderService provider);
+
+    /**
+     * Returns a String identifier (the actual contents is left to
+     * implementations) that uniquely represents this <tt>MetaContact</tt>
+     * in the containing <tt>MetaContactList</tt>
+     * @return String
+     */
+    public String getMetaContactID();
 }

File [changed]: MetaContactGroup.java
Url: https://sip-communicator-1-0-draft.dev.java.net/source/browse/sip-communicator-1-0-draft/src/net/java/sip/communicator/service/contactlist/MetaContactGroup.java?r1=1.1&r2=1.2
Delta lines:  +97 -6
--------------------
--- MetaContactGroup.java	3 Feb 2006 16:30:00 -0000	1.1
+++ MetaContactGroup.java	5 Feb 2006 16:06:57 -0000	1.2
@@ -6,14 +6,105 @@
  */
 package net.java.sip.communicator.service.contactlist;
 
+import java.util.*;
+
 /**
- *
+ * <tt>MetaContactGroup</tt>s are used to merge groups (often originating
+ * in different protocols).
+ * <p>
+ * A <tt>MetaContactGroup</tt> may contain contacts and some groups may
+ * also have sub-groups as children. To verify whether or not a particular
+ * group may contain subgroups, a developer has to call the
+ * <tt>canContainSubgroups()</tt> method
+ * <p>
  * @author Emil Ivov
  */
-public class MetaContactGroup
+public interface MetaContactGroup
 {
-    public MetaContactGroup()
-    {
-        super();
-    }
+    /**
+     * Returns a <tt>java.util.Iterator</tt> over the <tt>MetaContact</tt>s
+     * contained in this <tt>MetaContactGroup</tt>.
+     * @return a <tt>java.util.Iterator</tt> over the <tt>MetaContacts</tt> in
+     * this group.
+     */
+    public Iterator getChildContacts();
+
+    /**
+     * Returns the number of <tt>MetaContact</tt>s that this group contains
+     * <p>
+     * @return an int indicating the number of MetaContact-s that this group
+     * contains.
+     */
+    public int countChildContacts();
+
+    /**
+     * Returns an <tt>java.util.Iterator</tt> over the sub groups that this
+     * <tt>MetaContactGroup</tt> contains. Not all <tt>MetaContactGroup</tt>s
+     * can have sub groups. In case there are no subgroups in this
+     * <tt>MetaContactGroup</tt>, the method would return an empty list.
+     * The <tt>canContainSubgroups()</tt> method allows us to verify whether
+     * this is the case with the group at hand.
+     * <p>
+     * @return a <tt>java.util.Iterator</tt> containing all subgroups.
+     */
+    public Iterator getSubgroups();
+
+    /**
+     * Returns the number of subgroups that this <tt>MetaContactGroup</tt>
+     * contains.
+     * @return an int indicating the number of subgroups in this group.
+     */
+    public int countSubgroups();
+
+    /**
+     * Determines whether or not this group can contain subgroups. The method
+     * should be called befor creating subgroups in order to avoir invalid
+     * argument exceptions.
+     * <p>
+     * @return <tt>true</tt> if this groups can contain subgroups and
+     * <tt>false</tt> otherwise.
+     */
+    public boolean canContainSubgroups();
+
+    /**
+     * Returns the contact with the specified identifier
+     * @param metaContactID a String identifier obtained through the
+     * <tt>MetaContact.getMetaContactID()</tt> method.
+     * <p>
+     * @return the <tt>MetaContact</tt> with the specified idnetifier.
+     */
+    public MetaContact getMetaContact(String metaContactID);
+
+    /**
+     * Returns the meta contact on the specified index.
+     * @param index the index of the meta contact to return.
+     * @return the MetaContact with the specified index,
+     * <p>
+     * @throws java.lang.IndexOutOfBoundsException in case <tt>index</tt> is
+     * not a valid index for this group.
+     */
+    public MetaContact getMetaContact(int index)
+        throws IndexOutOfBoundsException;
+
+    /**
+     * Returns the <tt>MetaContactGroup</tt> with the specified name.
+     * @param groupName the name of the group to return.
+     * @return the <tt>MetaContactGroup</tt> with the specified name or null
+     * if no such group exists.
+     */
+    public MetaContactGroup getMetaContactSubgroup(String groupName);
+
+    /**
+     * Returns the <tt>MetaContactGroup</tt> with the specified index.
+     * <p>
+     * @param index the index of the group to return.
+     * @return the <tt>MetaContactGroup</tt> with the specified index.
+     * <p>
+     * @throws java.lang.IndexOutOfBoundsException if <tt>index</tt> is not
+     * a valid index.
+     */
+    public MetaContactGroup getMetaContactSubgroup(int index)
+        throws IndexOutOfBoundsException;
+
+
 }

File [changed]: MetaContactListException.java
Url: https://sip-communicator-1-0-draft.dev.java.net/source/browse/sip-communicator-1-0-draft/src/net/java/sip/communicator/service/contactlist/MetaContactListException.java?r1=1.1&r2=1.2
Delta lines:  +6 -1
-------------------
--- MetaContactListException.java	3 Feb 2006 16:30:07 -0000	1.1
+++ MetaContactListException.java	5 Feb 2006 16:06:57 -0000	1.2
@@ -1,4 +1,9 @@
-/** @todo add lgpl licence string*/
+/*
+ * SIP Communicator, the OpenSource Java VoIP and Instant Messaging client.
+ *
+ * Distributable under LGPL license.
+ * See terms of license at gnu.org.
+ */
 package net.java.sip.communicator.service.contactlist;
 
 /**

File [changed]: MetaContactListService.java
Url: https://sip-communicator-1-0-draft.dev.java.net/source/browse/sip-communicator-1-0-draft/src/net/java/sip/communicator/service/contactlist/MetaContactListService.java?r1=1.1&r2=1.2
Delta lines:  +46 -26
---------------------
--- MetaContactListService.java	3 Feb 2006 16:30:14 -0000	1.1
+++ MetaContactListService.java	5 Feb 2006 16:06:58 -0000	1.2
@@ -10,10 +10,10 @@
 import net.java.sip.communicator.service.contactlist.event.MetaContactListListener;
 
 /**
- * The <code>MetaContactListService</code> handles the global project contact
+ * The <tt>MetaContactListService</tt> handles the global project contact
  * list including contacts from all implemented protocols.
  * <p>
- * An implementation of the <code>MetaContactListService</code> would take care
+ * An implementation of the <tt>MetaContactListService</tt> would take care
  * of synchronizing the local copy ot the contact list with the  versions stored
  * on the various server protocols.
  * <p>
@@ -21,10 +21,10 @@
  * list should use this service rather than accessing protocol providers
  * directly.
  * <p>
- * The point of <code>MetaContact</code>s is being able to merge different
+ * The point of <tt>MetaContact</tt>s is being able to merge different
  * protocol specific contacts so that they represent a single person or identity.
- * Every protocol specific <code>Contact</code> would therefore automatically
- * be assigned to a corresponding <code>MetaContact</code>. A single
+ * Every protocol specific <tt>Contact</tt> would therefore automatically
+ * be assigned to a corresponding <tt>MetaContact</tt>. A single
  * MetaContact may containg multiple contacts (e.g. a single person often
  * has accounts in different protocols) while a single protocol specific
  * Contact may only be assigned to a exactly one MetaContact.
@@ -46,16 +46,36 @@
 public interface MetaContactListService
 {
     /**
-     * Returns the root <code>MetaContactGroup</code> in this contact list.
+     * Returns the root <tt>MetaContactGroup</tt> in this contact list.
      * All meta contacts and subgroups are children of the root meta contact
      * and references to them can only be obtained through it.
      *
-     * @return the root <code>MetaContactGroup</code> for this contact list.
+     * @return the root <tt>MetaContactGroup</tt> for this contact list.
      */
     public MetaContactGroup getRoot();
 
     /**
-     * Adds a listener for <code>MetaContactListChangeEvent</code>s posted after
+     * Returns the MetaContact containing the specified contact or null if no
+     * such MetaContact was found. The method can be used when for example
+     * we need to find the MetaContact that is the author of an incoming message
+     * and the corresponding ProtocolProviderService has only provided a
+     * <tt>Contact</tt> as its author.
+     * @return the MetaContact containing the speicified contact or null
+     * if no such contact is present in this contact list.
+     */
+    public MetaContact findMetaContactByContact(Contact contact);
+
+    /**
+     * Returns the MetaContact that corresponds to the specified metaContactID.
+     *
+     * @param metaContactID a String identifier of a meta contact.
+     * @return the MetaContact with the speicified string identifier or null
+     * if no such meta contact was found.
+     */
+    public MetaContact findMetaContactByID(String metaContactID);
+
+    /**
+     * Adds a listener for <tt>MetaContactListChangeEvent</tt>s posted after
      * the tree changes.
      *
      * @param l the listener to add
@@ -64,21 +84,21 @@
 
     /**
      * Removes a listener previously added with
-     * <code>addContactListListener</code>.
+     * <tt>addContactListListener</tt>.
      *
      * @param l the listener to remove
      */
     public void removeContactListListener(MetaContactListListener l);
 
     /**
-     * Makes the specified <code>contact</code> a child of the
-     * <code>newParent</code> MetaContact. If <code>contact</code> was
+     * Makes the specified <tt>contact</tt> a child of the
+     * <tt>newParent</tt> MetaContact. If <tt>contact</tt> was
      * previously a child of another meta contact, it will be removed from its
      * old parent before being added to the new one. If the specified contact
      * was the only child of its previous parent, then it (the previous parent)
      * will be removed.
      *
-     * @param contact the <code>Contact</code> to move to the
+     * @param contact the <tt>Contact</tt> to move to the
      * @param newParent the MetaContact where we'd like contact to be moved.
      *
      * @throws MetaContactListException with an appropriate code if the
@@ -90,7 +110,7 @@
     /**
      * Deletes the specified contact from both the local contact list and (if
      * applicable) the server stored contact list if supported by the
-     * corresponding protocol. If the <code>MetaContact</code> that contained
+     * corresponding protocol. If the <tt>MetaContact</tt> that contained
      * the given contact had no other children, it will be removed.
      * <p>
      * @param contact the contact to remove.
@@ -102,11 +122,11 @@
 
     /**
      * First makes the specified protocol provider create the contact as
-     * indicated by <code>contactID</code>, and then associates it to the
-     * _existing_ <code>metaContact</code> given as an argument.
+     * indicated by <tt>contactID</tt>, and then associates it to the
+     * _existing_ <tt>metaContact</tt> given as an argument.
      * <p>
      * @param provider the ProtocolProviderService that should create the
-     * contact indicated by <code>contactID</code>.
+     * contact indicated by <tt>contactID</tt>.
      * @param metaContact the meta contact where that the newly created contact
      * should be associated to.
      * @param contactID the identifier of the contact that the specified provider
@@ -121,7 +141,7 @@
 
     /**
      * First makes the specified protocol provider create a contact
-     * corresponding to the specified <code>contactID</code>, then creates a new
+     * corresponding to the specified <tt>contactID</tt>, then creates a new
      * MetaContact which will encapsulate the newly crated protocol specific
      * contact. Depending on implementations the method may sometimes need
      * time to complete as it may be necessary for an underlying protocol to
@@ -131,7 +151,7 @@
      * group on the protocol server, it will be created before the contact
      * itself.
      * <p>
-     * @param provider a ref to <code>ProtocolProviderService</code> instance
+     * @param provider a ref to <tt>ProtocolProviderService</tt> instance
      * which will create the actual protocol specific contact.
      * @param contactGroup the MetaContactGroup where the newly created meta
      * contact should be stored.
@@ -147,11 +167,11 @@
         throws MetaContactListException;
 
     /**
-     * Moves the specified <code>MetaContact</code> to <code>newGroup</code>.
+     * Moves the specified <tt>MetaContact</tt> to <tt>newGroup</tt>.
      * <p>
-     * @param metaContact the <code>MetaContact</code> to move.
-     * @param newGroup the <code>MetaContactGroup</code> that should be the
-     * new parent of <code>contact</code>.
+     * @param metaContact the <tt>MetaContact</tt> to move.
+     * @param newGroup the <tt>MetaContactGroup</tt> that should be the
+     * new parent of <tt>contact</tt>.
      *
      * @throws MetaContactListException with an appropriate code if the
      * operation fails for some reason.
@@ -161,7 +181,7 @@
         throws MetaContactListException;
 
     /**
-     * Removes the specified <code>metaContact</code> as well as all of its
+     * Removes the specified <tt>metaContact</tt> as well as all of its
      * underlying contacts.
      * <p>
      * @param metaContact the metaContact to remove.
@@ -172,13 +192,13 @@
         throws MetaContactListException;
 
     /**
-     * Creates a <code>MetaContactGroup</code> with the specified group name.
+     * Creates a <tt>MetaContactGroup</tt> with the specified group name.
      * Initially, the group would only be created locally. Corresponding
      * server stored groups will be created on the fly, whenever real protocol
      * specific contacts are added to the group if the protocol lying behind
      * them supports that.
      * <p>
-     * @param groupName the name of the <code>MetaContactGroup</code> to create.
+     * @param groupName the name of the <tt>MetaContactGroup</tt> to create.
      *
      * @throws MetaContactListException with an appropriate code if the
      * operation fails for some reason.
@@ -191,7 +211,7 @@
      * specific groups and all their children. If some of the children belong to
      * server stored contact lists, they will be updated to not include the
      * child contacts any more.
-     * @param groupToRemove the <code>MetaContactGroup</code> to have removed.
+     * @param groupToRemove the <tt>MetaContactGroup</tt> to have removed.
      *
      * @throws MetaContactListException with an appropriate code if the
      * operation fails for some reason.




---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe at sip-communicator-1-0-draft.dev.java.net
For additional commands, e-mail: cvs-help at sip-communicator-1-0-draft.dev.java.net





More information about the commits mailing list