Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 5b0cad59 authored by Ricki Hirner's avatar Ricki Hirner
Browse files

Update OpenTasks contract

parent 3149daac
Loading
Loading
Loading
Loading
+63 −10
Original line number Diff line number Diff line
@@ -512,7 +512,7 @@ public final class TaskContract
        String DESCRIPTION = "description";

        /**
         * An URL for this task. Must be a valid URL if not <code>null</code>-
         * The URL iCalendar field for this task. Must be a valid URI if not <code>null</code>-
         * <p>
         * Value: String
         * </p>
@@ -1036,27 +1036,80 @@ public final class TaskContract
        String INSTANCE_DURATION = "instance_duration";

        /**
         * The start of the original instance as specified in the master task. For non-recurring task instances this equals the value of {@link
         * #INSTANCE_START}, except that `null` values are represented as `0`.
         * The start of the original instance as specified in the master task. For non-recurring task instances this is {@code null}.
         * <p>
         * For recurring tasks, these are the timestamps which have been derived from the recurrence rule or dates, except those specified as exdates.
         */
        String INSTANCE_ORIGINAL_TIME = "instance_original_time";

        /**
         * The distance of the instance from the current one. For closed instances this is always {@code -1}, for the current instance this is {@code 0}. For
         * the instance after the current one this is {@code 1}, for the instance after that one it's {@code 2}, etc..
         * <p>
         * Value: Integer
         * <p>
         * read-only
         */
        String DISTANCE_FROM_CURRENT = "distance_from_current";
    }


    /**
     * Instances of a task. At present this table is read only. Currently it contains exactly one entry per task (and task exception), so it's merely a copy of
     * {@link Tasks}.
     * A table containing one entry per task instance. This table is writable in order to allow modification of single instances of a task. Write operations to
     * this table will be converted into operations on overrides and forwarded to the task table.
     * <p>
     * TODO: Insert all instances of recurring the tasks.
     * </p>
     * Note: The {@link #DTSTART}, {@link #DUE} values of instances of recurring tasks represent the actual instance values, i.e. they are different for each
     * instance ({@link #DURATION} is always {@code null}).
     * <p>
     * TODO: In later releases it's planned to provide a convenient interface to add, change or delete task instances via this URI.
     * </p>
     * Also, none of the instances are recurring themselves, so {@link #RRULE}, {@link #RDATE} and {@link #EXDATE} are always {@code null}.
     * <p>
     * TODO: Insert all instances of recurring tasks.
     * <p>
     * The following operations are supported:
     * <p>
     * <h2>Insert</h2>
     * <p>
     * Note, the data of an insert must not contain the fields {@link #RRULE}, {@link #RDATE} or {@link #EXDATE}. If the new instance belongs to an existing
     * task the data must contain the fields {@link #ORIGINAL_INSTANCE_ID} and {@link #ORIGINAL_INSTANCE_TIME}. Also note, this table supports writing {@link
     * #DURATION} (if the instance has a {@link #DTSTART}), but reading it back will always return a {@code null} {@link #DURATION} and a non-{@code null}
     * {@link #DUE} date. Reading the task in the tasks table will, however, return the original {@link #DURATION}.
     * <p>
     * If there already is an instance (with or without override) for the given {@link #ORIGINAL_INSTANCE_ID} and {@link #ORIGINAL_INSTANCE_TIME} an exception
     * is thrown.
     * <p>
     * <table> <tr><th>ORIGINAL_INSTANCE_ID value</th><th>Result</th></tr> <tr><td>absent or empty</td><td>A new non-recurring task is created with the given
     * values.</td></tr> <tr><td>a valid {@link Tasks} row {@code _ID}</td><td>An {@link #RDATE} for the given {@link #ORIGINAL_INSTANCE_TIME} time is added to
     * the given master task, any {@link #EXDATE} for this time is removed. The task is inserted as an override to the given master. No fields are inherited
     * though. {@link #ORIGINAL_INSTANCE_ALLDAY} will be set to {@link #IS_ALLDAY} of the master.
     * <p>
     * Note, if the given master is non-recurring, this operation will turn it into a recurring task. </td></tr> <tr><td>invalid {@link Tasks} row {@code
     * _ID}</td><td>An exception is thrown.</td></tr></table>
     * <p>
     * <h2>Update</h2>
     * <p>
     * Note, the data of an update must not contain any fields related to recurrence ({@link #RRULE}, {@link #RDATE}, {@link #EXDATE}, {@link
     * #ORIGINAL_INSTANCE_ID}, {@link #ORIGINAL_INSTANCE_TIME} and {@link #ORIGINAL_INSTANCE_ALLDAY}). Also note, this table supports writing {@link #DURATION}
     * (if the instance has a {@link #DTSTART}), but reading it back will always return a {@code null} {@link #DURATION} and a non-{@code null} {@link #DUE}
     * date. Reading the task in the tasks table will, however, return the original {@link #DURATION}.
     * <p>
     * <table> <tr><th>Target task type</th><th>Result</th></tr> <tr><td>Recurring master task</td><td>A new override is created with the given data.<p> Note,
     * any fields which are not provided are inherited from the master, except for {@link #DTSTART} and {@link #DUE} which will be inherited from the instance
     * and {@link #DURATION}, {@link #RRULE}, {@link #RDATE} and {@link #EXDATE} which are set to {@code null}. {@link #ORIGINAL_INSTANCE_ID}, {@link
     * #ORIGINAL_INSTANCE_TIME} and {@link #ORIGINAL_INSTANCE_ALLDAY} will be set accordingly.</td></tr> <tr><td>Single instance task</td><td>The task is
     * updated with the given values.</td></tr> <tr><td>Recurrence override with existing master</td><td>The task is updated with the given values.</td></tr>
     * <tr><td>Recurrence override without existing master</td><td>The task is updated with the given values.</td></tr> </table>
     * <p>
     * <h2>Delete</h2>
     * <p>
     * <table> <tr><th>Target task type</th><th>Result</th></tr> <tr><td>Recurring master task</td><td>An {@link #EXDATE} for this instance is added, any {@link
     * #RDATE} for this instance is removed. The instance row is removed.<p> TODO: mark the task deleted if the remaining recurrence set is empty </td></tr>
     * <tr><td>Single instance task</td><td>The {@link Tasks#_DELETED} flag of the task is set.</td></tr> <tr><td>Recurrence override with existing
     * master</td><td>The {@link Tasks#_DELETED} flag of the override is set, an {@link #EXDATE} for this instance is added to the master, any {@link #RDATE}
     * for this instance is removed from the master. TODO: mark the master deleted if the remaining recurrence set of the master is empty </td></tr>
     * <tr><td>Recurrence override without existing master</td><td>The {@link Tasks#_DELETED} flag of the task is set.</td></tr> </table>
     *
     * @author Yannic Ahrens <yannic@dmfs.org>
     * @author Yannic Ahrens
     * @author Marten Gajda
     */
    public static final class Instances implements TaskColumns, InstanceColumns
    {
+1 −1
Original line number Diff line number Diff line
@@ -34,7 +34,7 @@ public final class UriFactory
    UriFactory(String authority)
    {
        mAuthority = authority;
        mUriMap.put((String) null, Uri.parse("content://" + authority));
        mUriMap.put(null, Uri.parse("content://" + authority));
    }