Java API for mojo system.

mojo/public/java/src/org/chromium/mojo/system/DataPipe.java

Index: mojo/public/java/src/org/chromium/mojo/system/DataPipe.java
diff --git a/mojo/public/java/src/org/chromium/mojo/system/DataPipe.java b/mojo/public/java/src/org/chromium/mojo/system/DataPipe.java
new file mode 100644
index 0000000000000000000000000000000000000000..00b8c7d1d8d13a31bf8664547e4e7ea861c849bb
--- /dev/null
+++ b/mojo/public/java/src/org/chromium/mojo/system/DataPipe.java
@@ -0,0 +1,209 @@
+// Copyright 2014 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+package org.chromium.mojo.system;
+
+import java.nio.ByteBuffer;
+
+/**
+ * TODO(qsr): Insert description here.
+ */
+public interface DataPipe {
+
+    /**
+     * TODO(qsr): Insert description here.
+     */
+    public static class CreateFlags extends Flags<CreateFlags> {
+        private static final int FLAG_NONE = 0;
+        private static final int FLAG_MAY_DISCARD = 1 << 0;
+
+        /**
+         * Dedicated constructor.
+         *
+         * @param flags initial value of the flags.
+         */
+        protected CreateFlags(int flags) {
+            super(flags);
+        }
+
+        /**
+         * Change the may-discard bit of this flag.
+         *
+         * @param mayDiscard the new value of the may-discard bit.
+         * @return this.
+         */
+        public CreateFlags mayDiscard(boolean mayDiscard) {
+            return setFlag(FLAG_MAY_DISCARD, mayDiscard);
+        }
+
+        /**
+         * @return flags with no bit set.
+         */
+        public static CreateFlags none() {
+            return new CreateFlags(FLAG_NONE);
+        }
+
+    }
+
+    /**
+     * TODO(qsr): Insert description here.
+     */
+    public static class CreateOptions {
+        public CreateFlags flags;
+        public int elementNumBytes;
+        public int capacityNumBytes;

[bulach, 2014/04/14 17:39:56]

nit: we normally don't expose naked members.
alternatives:
- make them final, and have a ctor taking all of them.
- keep them private with getters / setters where needed.

[qsr, 2014/04/15 08:37:37]

 I cannot do the first. This is an API. I want use to be able to update the
version of the API without having to modify their code if possible, having a
ctor will force to change all callers. Getter/Setter is possible if we really do
not want the naked field, but make the declaration and usage very verbose for
something that is really just a plain data container... Also, I didn't find
anything in either google or a android style guide against it.

+    }
+
+    /**
+     * Flag for the write operations on MessagePipeHandle .
+     */
+    public static class WriteFlags extends Flags<WriteFlags> {
+        private static final int FLAG_NONE = 0;
+        private static final int FLAG_ALL_OR_NONE = 1 << 0;
+
+        /**
+         * Dedicated constructor.
+         *
+         * @param flags initial value of the flags.
+         */
+        private WriteFlags(int flags) {
+            super(flags);
+        }
+
+        /**
+         * Change the all-or-none bit of those flags.
+         *
+         * @param allOrNone the new value of all-or-none bit.
+         * @return this.
+         */
+        public WriteFlags allOrNone(boolean allOrNone) {
+            return setFlag(FLAG_ALL_OR_NONE, allOrNone);
+        }
+
+        /**
+         * @return a flag with no bit set.
+         */
+        public static WriteFlags none() {
+            return new WriteFlags(FLAG_NONE);
+        }
+    }
+
+    /**
+     * Flag for the read operations on MessagePipeHandle.
+     */
+    public static class ReadFlags extends Flags<ReadFlags> {
+        private static final int FLAG_NONE = 0;
+        private static final int FLAG_ALL_OR_NONE = 1 << 0;
+        private static final int FLAG_DISCARD = 1 << 1;
+        private static final int FLAG_QUERY = 1 << 2;
+
+        /**
+         * Dedicated constructor.
+         *
+         * @param flags initial value of the flag.
+         */
+        private ReadFlags(int flags) {
+            super(flags);
+        }
+
+        /**
+         * Change the all-or-none bit of this flag.
+         *
+         * @param allOrNone the new value of the all-or-none bit.
+         * @return this.
+         */
+        public ReadFlags allOrNone(boolean allOrNone) {
+            return setFlag(FLAG_ALL_OR_NONE, allOrNone);
+        }
+
+        /**
+         * Change the discard bit of this flag.
+         *
+         * @param discard the new value of the discard bit.
+         * @return this.
+         */
+        public ReadFlags discard(boolean discard) {
+            return setFlag(FLAG_DISCARD, discard);
+        }
+
+        /**
+         * Change the query bit of this flag.
+         *
+         * @param query the new value of the query bit.
+         * @return this.
+         */
+        public ReadFlags query(boolean query) {
+            return setFlag(FLAG_QUERY, query);
+        }
+
+        /**
+         * @return a flag with no bit set.
+         */
+        public static ReadFlags none() {
+            return new ReadFlags(FLAG_NONE);

[bulach, 2014/04/14 17:39:56]

as above..

[qsr, 2014/04/15 08:37:37]

 So I guess the issue was not with all(), but with flags in general.

 I wrote those flags because I wanted the API to be clear about what flag it
expected. Unfortunately java doesn't have anything that looks like typedef, so
if I want to have something clear, I need to use class and not int.

 I do not think this is really an issue as all those flags are used for I/O, so
the creation of an object should not be relevant performance wise. Now if you
have any idea on how to do something better, I'm all for it, but I'd really like
the solution to have an API that specify exactly what you should put in it.

+        }
+
+    }
+
+    /**
+     * TODO(qsr): Insert description here.
+     */
+    public static interface ProducerHandle extends Handle {
+        /**
+         * TODO(qsr):
+         *
+         * @param elements
+         * @param flags
+         * @return number of written bytes.
+         */
+        public int writeData(ByteBuffer elements, WriteFlags flags);
+
+        /**
+         * TODO(qsr):
+         *
+         * @param numBytes
+         * @param flags
+         * @return TODO(qsr)
+         */
+        public java.nio.ByteBuffer beingWriteData(int numBytes, WriteFlags flags);

[bulach, 2014/04/14 17:39:56]

nit: just ByteBuffer, since it's already imported?

[qsr, 2014/04/15 08:37:37]

Done.

+
+        /**
+         * TODO(qsr):
+         *
+         * @param numBytesWritten
+         */
+        public void endWriteData(int numBytesWritten);
+    }
+
+    /**
+     * TODO(qsr): Insert description here.
+     */
+    public static interface ConsumerHandle extends Handle {
+        /**
+         * TODO(qsr):
+         *
+         * @param elements
+         * @param flags
+         * @return TODO(qsr):
+         */
+        public int readData(ByteBuffer elements, ReadFlags flags);
+
+        /**
+         * TODO(qsr):
+         *
+         * @param numBytes
+         * @param flags
+         * @return TODO(qsr):
+         */
+        public java.nio.ByteBuffer beingReadData(int numBytes, ReadFlags flags);

[bulach, 2014/04/14 17:39:56]

nit: as above

[qsr, 2014/04/15 08:37:37]

Done.

+
+        /**
+         * TODO(qsr):
+         *
+         * @param numBytesRead
+         */
+        public void endReadData(int numBytesRead);
+    }
+
+}