// ************************************************************************
//    $Id: RawMemoryAccess.java 568 2005-07-12 00:33:41Z mdeters $
// ************************************************************************
//
//                                jRate
//
//               Copyright (C) 2001-2005 by Angelo Corsaro.
//                         <corsaro@cse.wustl.edu>
//                          All Rights Reserved.
//
//   Permission to use, copy, modify, and distribute this software and
//   its  documentation for any purpose is hereby  granted without fee,
//   provided that the above copyright notice appear in all copies and
//   that both that copyright notice and this permission notice appear
//   in  supporting  documentation. I don't make  any  representations
//   about the  suitability  of this  software for any  purpose. It is
//   provided "as is" without express or implied warranty.
//
//
// *************************************************************************
//
// *************************************************************************

package javax.realtime;

/**
 * A class permitting access to specific memory offsets within the
 * process address space.
 *
 * <p>jRate programs should refer to {@link RealtimeSystem
 * RealtimeSystem's} {@link RealtimeSystem#BYTE_ORDER
 * <code>BYTE_ORDER</code> field} to determine if they are running on
 * big-endian or little-endian systems.
 *
 * <p>Raw memory areas cannot contain references to Java objects.
 *
 * @author <a href="mailto:mdeters@morgandeters.com">Morgan Deters</a>
 * @version 1.0
 * @since 0.3.8
 */
public class RawMemoryAccess {
    /**
     * Constructs a raw memory accessor associated to a memory area of
     * the given memory type and size.
     *
     * @param type the memory type
     * @param size the size of the memory area
     * @throws SecurityException the current execution context does
     * not have permission to access physical memory, or memory of the
     * given type
     * @throws OffsetOutOfBoundsException this exception is never
     * thrown; it is in the signature to be spec-compliant
     * @throws SizeOutOfBoundsException the size is negative or too
     * large
     * @throws UnsupportedPhysicalMemoryException the hardware does
     * not support this type of memory
     * @throws MemoryTypeConflictException the type parameter's
     * attributes conflict with each other
     */
    public RawMemoryAccess(Object type, long size)
        throws OffsetOutOfBoundsException,
               SizeOutOfBoundsException,
               UnsupportedPhysicalMemoryException,
               MemoryTypeConflictException {
        // When this is implemented, make sure to check permission for
        // the range of physical addresses that end up being used.
        RealtimeSystem.getSecurityManager().checkAccessPhysical();
        throw new UnimplementedFeatureError();
    }

    /**
     * Constructs a raw memory accessor associated to a memory area of
     * the given memory type and size, based at the given offset.
     *
     * @param type the memory type
     * @param base the base offset of the memory area
     * @param size the size of the memory area
     * @throws SecurityException the current execution context does
     * not have permission to access physical memory, or memory of the
     * given type
     * @throws OffsetOutOfBoundsException this exception is never
     * thrown; it is in the signature to be spec-compliant
     * @throws SizeOutOfBoundsException the size is negative or too
     * large
     * @throws UnsupportedPhysicalMemoryException the hardware does
     * not support this type of memory
     * @throws MemoryTypeConflictException the type parameter's
     * attributes conflict with each other or with the specified base
     * offset
     */
    public RawMemoryAccess(Object type, long base, long size)
        throws OffsetOutOfBoundsException,
               SizeOutOfBoundsException,
               UnsupportedPhysicalMemoryException,
               MemoryTypeConflictException {
        RealtimeSystem.getSecurityManager().
            checkAccessPhysicalRange(base, base + size);
        throw new UnimplementedFeatureError();
    }

    /**
     * Get the byte at the given offset.
     *
     * @param offset the memory offset to access
     * @return the byte at the given offset
     * @throws OffsetOutOfBoundsException the given offset is negative
     * or outside the range of this raw memory area
     * @throws SizeOutOfBoundsException satisfying the request would
     * require accessing storage beyond the end of the memory area
     */
    public byte getByte(long offset)
        throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
        throw new UnimplementedFeatureError();
    }

    /**
     * Get a consecutive sequence of bytes at the given offset.
     *
     * @param offset the memory offset to access
     * @param bytes the array to copy bytes into
     * @param low the offset into the array at which to start copying
     * @param number the number of bytes to copy
     * @throws OffsetOutOfBoundsException the given offset is negative
     * or outside the range of this raw memory area
     * @throws SizeOutOfBoundsException satisfying the request would
     * require accessing storage beyond the end of the memory area
     */
    public void getBytes(long offset, byte[] bytes, int low, int number)
        throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
        throw new UnimplementedFeatureError();
    }

    /**
     * Get the int at the given offset.
     *
     * @param offset the memory offset to access
     * @return the int at the given offset
     * @throws OffsetOutOfBoundsException the given offset is negative
     * or outside the range of this raw memory area
     * @throws SizeOutOfBoundsException satisfying the request would
     * require accessing storage beyond the end of the memory area
     */
    public int getInt(long offset)
        throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
        throw new UnimplementedFeatureError();
    }

    /**
     * Get a consecutive sequence of ints at the given offset.
     *
     * @param offset the memory offset to access
     * @param ints the array to copy ints into
     * @param low the offset into the array at which to start copying
     * @param number the number of ints to copy
     * @throws OffsetOutOfBoundsException the given offset is negative
     * or outside the range of this raw memory area
     * @throws SizeOutOfBoundsException satisfying the request would
     * require accessing storage beyond the end of the memory area
     */
    public void getInts(long offset, int[] ints, int low, int number)
        throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
        throw new UnimplementedFeatureError();
    }

    /**
     * Get the long at the given offset.
     *
     * @param offset the memory offset to access
     * @return the long at the given offset
     * @throws OffsetOutOfBoundsException the given offset is negative
     * or outside the range of this raw memory area
     * @throws SizeOutOfBoundsException satisfying the request would
     * require accessing storage beyond the end of the memory area
     */
    public long getLong(long offset)
        throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
        throw new UnimplementedFeatureError();
    }

    /**
     * Get a consecutive sequence of longs at the given offset.
     *
     * @param offset the memory offset to access
     * @param longs the array to copy longs into
     * @param low the offset into the array at which to start copying
     * @param number the number of longs to copy
     * @throws OffsetOutOfBoundsException the given offset is negative
     * or outside the range of this raw memory area
     * @throws SizeOutOfBoundsException satisfying the request would
     * require accessing storage beyond the end of the memory area
     */
    public void getLongs(long offset, long[] longs, int low, int number)
        throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
        throw new UnimplementedFeatureError();
    }

    /**
     * Get the short at the given offset.
     *
     * @param offset the memory offset to access
     * @return the short at the given offset
     * @throws OffsetOutOfBoundsException the given offset is negative
     * or outside the range of this raw memory area
     * @throws SizeOutOfBoundsException satisfying the request would
     * require accessing storage beyond the end of the memory area
     */
    public short getShort(long offset)
        throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
        throw new UnimplementedFeatureError();
    }

    /**
     * Get a consecutive sequence of shorts at the given offset.
     *
     * @param offset the memory offset to access
     * @param shorts the array to copy shorts into
     * @param low the offset into the array at which to start copying
     * @param number the number of shorts to copy
     * @throws OffsetOutOfBoundsException the given offset is negative
     * or outside the range of this raw memory area
     * @throws SizeOutOfBoundsException satisfying the request would
     * require accessing storage beyond the end of the memory area
     */
    public void getShorts(long offset, short[] shorts, int low, int number)
        throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
        throw new UnimplementedFeatureError();
    }

    /**
     * Set the byte at the given offset.
     *
     * @param offset the memory offset to access
     * @param value the value to assign the byte in memory
     * @throws OffsetOutOfBoundsException the given offset is negative
     * or outside the range of this raw memory area
     * @throws SizeOutOfBoundsException satisfying the request would
     * require accessing storage beyond the end of the memory area
     */
    public void setByte(long offset, byte value)
        throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
        throw new UnimplementedFeatureError();
    }

    /**
     * Set a consecutive sequence of bytes at the given offset.
     *
     * @param offset the memory offset to access
     * @param bytes the array to copy bytes from
     * @param low the offset into the array at which to start copying
     * @param number the number of bytes to copy
     * @throws OffsetOutOfBoundsException the given offset is negative
     * or outside the range of this raw memory area
     * @throws SizeOutOfBoundsException satisfying the request would
     * require accessing storage beyond the end of the memory area
     */
    public void setBytes(long offset, byte[] bytes, int low, int number)
        throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
        throw new UnimplementedFeatureError();
    }

    /**
     * Set the int at the given offset.
     *
     * @param offset the memory offset to access
     * @param value the value to assign the int in memory
     * @throws OffsetOutOfBoundsException the given offset is negative
     * or outside the range of this raw memory area
     * @throws SizeOutOfBoundsException satisfying the request would
     * require accessing storage beyond the end of the memory area
     */
    public void setInt(long offset, int value)
        throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
        throw new UnimplementedFeatureError();
    }

    /**
     * Set a consecutive sequence of ints at the given offset.
     *
     * @param offset the memory offset to access
     * @param ints the array to copy ints from
     * @param low the offset into the array at which to start copying
     * @param number the number of ints to copy
     * @throws OffsetOutOfBoundsException the given offset is negative
     * or outside the range of this raw memory area
     * @throws SizeOutOfBoundsException satisfying the request would
     * require accessing storage beyond the end of the memory area
     */
    public void setInts(long offset, int[] ints, int low, int number)
        throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
        throw new UnimplementedFeatureError();
    }

    /**
     * Set the long at the given offset.
     *
     * @param offset the memory offset to access
     * @param value the value to assign the long in memory
     * @throws OffsetOutOfBoundsException the given offset is negative
     * or outside the range of this raw memory area
     * @throws SizeOutOfBoundsException satisfying the request would
     * require accessing storage beyond the end of the memory area
     */
    public void setLong(long offset, long value)
        throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
        throw new UnimplementedFeatureError();
    }

    /**
     * Set a consecutive sequence of longs at the given offset.
     *
     * @param offset the memory offset to access
     * @param longs the array to copy longs from
     * @param low the offset into the array at which to start copying
     * @param number the number of longs to copy
     * @throws OffsetOutOfBoundsException the given offset is negative
     * or outside the range of this raw memory area
     * @throws SizeOutOfBoundsException satisfying the request would
     * require accessing storage beyond the end of the memory area
     */
    public void setLongs(long offset, long[] longs, int low, int number)
        throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
        throw new UnimplementedFeatureError();
    }

    /**
     * Set the short at the given offset.
     *
     * @param offset the memory offset to access
     * @param value the value to assign the short in memory
     * @throws OffsetOutOfBoundsException the given offset is negative
     * or outside the range of this raw memory area
     * @throws SizeOutOfBoundsException satisfying the request would
     * require accessing storage beyond the end of the memory area
     */
    public void setShort(long offset, short value)
        throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
        throw new UnimplementedFeatureError();
    }

    /**
     * Set a consecutive sequence of shorts at the given offset.
     *
     * @param offset the memory offset to access
     * @param shorts the array to copy shorts from
     * @param low the offset into the array at which to start copying
     * @param number the number of shorts to copy
     * @throws OffsetOutOfBoundsException the given offset is negative
     * or outside the range of this raw memory area
     * @throws SizeOutOfBoundsException satisfying the request would
     * require accessing storage beyond the end of the memory area
     */
    public void setShorts(long offset, short[] shorts, int low, int number)
        throws OffsetOutOfBoundsException, SizeOutOfBoundsException {
        throw new UnimplementedFeatureError();
    }

    /**
     * Returns the virtual memory location at which this physical
     * memory area is mapped.
     *
     * @return the virtual memory location to which this physical
     * memory area is mapped
     */
    public long getMappedAddress() {
        throw new UnimplementedFeatureError();
    }

    /**
     * Map the physical memory range into virtual memory.
     *
     * @return zero
     */
    public long map() {
        throw new UnimplementedFeatureError();
    }

    /**
     * Map the physical memory range into virtual memory.
     *
     * @param base the location to map in virtual memory
     * @return zero
     */
    public long map(long base) {
        throw new UnimplementedFeatureError();
    }

    /**
     * Map the physical memory range into virtual memory.
     *
     * @param base the location to map in virtual memory
     * @param size the size of the block to map
     * @return zero
     */
    public long map(long base, long size) {
        throw new UnimplementedFeatureError();
    }

    /**
     * Unmap the physical memory range from virtual memory.
     */
    public void unmap() {
        throw new UnimplementedFeatureError();
    }
}