svn commit: r790803 - /commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer.java

Author: mturk
Date: Fri Jul  3 06:35:54 2009
New Revision: 790803

URL: http://svn.apache.org/viewvc?rev=790803&view=rev
Log:
Readd Pointer as interface

Added:
    commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer.java   (with props)

Added: commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer.java
URL: http://svn.apache.org/viewvc/commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer.java?rev=790803&view=auto
==============================================================================
--- commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer.java (added)
+++ commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer.java Fri Jul  3 06:35:54 2009
@@ -0,0 +1,174 @@
+/* Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.runtime;
+
+/** Represents the Operating System C/C++ pointer.
+ * <p>
+ * <b>Warning:</b><br/>Using this class improperly may crash the running JVM.
+ * </p>
+ * @since Runtime 1.0
+ */
+public interface Pointer extends Comparable<Pointer>
+{
+
+    /**
+     * Represents a C/C++ NULL {@code pointer}.
+     */
+    public static final Pointer NULL = NativePointer.NULL;
+
+    /**
+     * Address of the internal pointer.
+     * <p>
+     * Depending on the operating system the {@code Number} can be
+     * either {@code Integer} for 32 bit systems of {@code Long} for
+     * a 64 bit system.
+     *</p>
+     *
+     * @return Internal pointer address casted to the {@code Number}.
+     */
+    public Number address();
+
+    /**
+     * Size of the memory area this pointer consumes.
+     * <p>
+     * If the {@code this} Pointer does not have a length
+     * the returned size if Pointer {@code SIZEOF}.
+     *</p>
+     *
+     * @return Internal pointer size.
+     */
+    public long sizeof();
+
+    /**
+     * Check if the pointer is valid
+     * @return true if the internal pointer is not {@code NULL}.
+     */
+    public boolean IsNull();
+
+    /**
+     * Compares this {@code Pointer} to the specified object.
+     *
+     * @param other a {@code Pointer}
+     * @return  true if the class of this {@code Pointer} object and the
+     *      class of {@code other} are exactly equal, and the C/C++
+     *      pointers being pointed to by these objects are also
+     *      equal. Returns false otherwise.
+     */
+    @Override
+    public boolean equals(Object other);
+
+
+    /**
+     * Free the allocated resource by the Operating system.
+     * <p>
+     * Note that {@code Object.finalize()} method will call
+     * this function. However if the native code can block for
+     * long time explicit {@code free()} should be called.
+     * </p>
+     * @see NativePointer#finalize()
+     * @throws Throwable the {@code Exception} raised by this method.
+     */
+    public void free()
+        throws Throwable;
+
+    /**
+     * Get a {@code byte} value this {@code pointer} contains at the
+     * {@code index}.
+     *
+     * @return a {@code byte} at {@code index}.
+     * @throws IndexOutOfBoundsException if {@code index} would cause access
+     *          outside the pointer address space.
+     * @throws NullPointerException if pointer is {@code null}.
+     */
+    public int    peek(int index)
+        throws IndexOutOfBoundsException, NullPointerException;
+
+    /**
+     * Set a {@code byte} value to this {@code pointer} at the
+     * {@code index} location.
+     *
+     * @param value Value to set at {@code index}.
+     * @throws IndexOutOfBoundsException if {@code index} would cause access
+     *          outside the pointer address space.
+     * @throws NullPointerException if pointer is {@code null}.
+     */
+    public void poke(int index, int value)
+        throws IndexOutOfBoundsException, NullPointerException;
+
+    /**
+     * Copy the memory area from {@code this} pointer to {@code dst}.
+     * <p>
+     * Method uses the {@code memcpy} function to do a copying, meaning
+     * that {@code source} and {@code destination} memory areas should
+     * not overlap.
+     * </p>
+     *
+     * @param srcPos starting position in the source memory.
+     * @param dst destination {@code Pointer}.
+     * @param dstPos starting position in the destination memory.
+     * @param length the number of bytes to be copied.
+     *
+     * @throws IllegalArgumentException if the {@code srcPos} or
+     *          {@code dstPos} is {@code negative} or {@code length}
+     *          is {@code zero}.
+     * @throws IndexOutOfBoundsException if the operation would cause
+     *          access of data outside allocated memory bounds.
+     * @throws NullPointerException if {@code this} or {@code dst} is
+     *          {@code null}.
+     */
+    public void copy(long srcPos, Pointer dst,
+                              long dstPos, long length)
+        throws IndexOutOfBoundsException, IllegalArgumentException,
+               NullPointerException;
+
+    /**
+     * Copy the memory area from pointer {@code src} to {@code this} pointer.
+     * <p>
+     * Method uses the {@code memmove} function to do a copying, meaning
+     * that {@code source} and {@code destination} memory areas can overlap.
+     * </p>
+     *
+     * @param src source {@code Pointer}.
+     * @param srcPos starting position in the source memory.
+     * @param dstPos starting position in our memory area.
+     * @param length the number of bytes to be copied.
+     *
+     * @throws IllegalArgumentException if the {@code srcPos} or
+     *          {@code dstPos} is {@code negative} or {@code length}
+     *          is {@code zero}.
+     * @throws IndexOutOfBoundsException if the operation would cause
+     *          access of data outside allocated memory bounds.
+     * @throws NullPointerException if {@code this} or {@code dst} is
+     *          {@code null}.
+     */
+    public void move(Pointer src, long srcPos,
+                              long dstPos, long length)
+        throws IndexOutOfBoundsException, IllegalArgumentException,
+               NullPointerException;
+
+
+    /**
+     * Returns a string representation of the Pointer.
+     * The returned string is hexadecimal representation of the underlying
+     * pointer.
+     * @return a hexadecimal representation of the pointer.
+     */
+    @Override
+    public String toString();
+
+}
+

Propchange: commons/sandbox/runtime/trunk/src/main/java/org/apache/commons/runtime/Pointer.java
------------------------------------------------------------------------------
    svn:eol-style = native