change num() to imapNumber() and nntpNumber(), add comments about semantics

[org.ibex.mail.git] / src / org / ibex / mail / target / Mailbox.java

diff --git a/src/org/ibex/mail/target/Mailbox.java b/src/org/ibex/mail/target/Mailbox.java
index 13b376f..dbc91bf 100644 (file)
--- a/src/org/ibex/mail/target/Mailbox.java
+++ b/src/org/ibex/mail/target/Mailbox.java
@@ -79,6 +79,7 @@ public abstract class Mailbox extends JS.Obj implements Target {
             public void    recent(boolean on) { }
             public void    set(String key, String val) { throw new MailException("not supported"); }
             public String  get(String key) { throw new MailException("not supported"); }
+            public int     nntpNumber() { throw new MailException("not supported"); }
             public int flags() {
                 return 
                     (deleted() ? Flag.DELETED : 0) |
@@ -118,10 +119,28 @@ public abstract class Mailbox extends JS.Obj implements Target {
         public abstract Message cur();
         public abstract Headers head();
         public abstract boolean next();
-        public abstract int     uid();
-        public abstract int     num();
         public abstract void    delete();
 
+        /** a unique identifier for this message */
+        public abstract int     uid();
+
+        /**
+         *  Message number according to IMAP semantics.
+         *    - no two messages in the same mailbox may have the same imapNumber
+         *    - sorting by uid must yield the same order as sorting them by imapNumber
+         *    - imapNumber may only change if uidValidity changes
+         *    - if uidValidity changes, imapNumbers may change or be reused
+         */
+        public abstract int     imapNumber();
+
+        /**
+         *  Message number according to NNTP semantics.
+         *    - no two messages in the same mailbox may have the same nntpNumber
+         *    - article number may NEVER change or EVER be reused
+         *    - uidValidity is irrelevant
+         */
+        public abstract int     nntpNumber();
+
         public abstract void    set(String key, String val);
         public abstract String  get(String key);
 
@@ -152,7 +171,8 @@ public abstract class Mailbox extends JS.Obj implements Target {
             public boolean next() { return it.next(); }
             public int     uid() { return it.uid(); }
             public int     flags() { return it.flags(); }
-            public int     num() { return it.num(); }
+            public int     nntpNumber() { return it.nntpNumber(); }
+            public int     imapNumber() { return it.imapNumber(); }
             public void    set(String key, String val) { it.set(key, val); }
             public String  get(String key) { return it.get(key); }
             public void    delete() { it.delete(); }
@@ -188,7 +208,8 @@ public abstract class Mailbox extends JS.Obj implements Target {
             public boolean next() { return false; }
             public int     uid() { return 0; }
             public int     flags() { return 0; }
-            public int     num() { return 0; }
+            public int     imapNumber() { return 0; }
+            public int     nntpNumber() { throw new RuntimeException("this mailbox does not keep article numbers"); }
             public void    set(String key, String val) { }
             public String  get(String key) { return null; }
             public void    delete() { }