create subclass Readable to FragmentedSubIO to allow future implementations of Writable and ReadWrite

Author: lecousin

README.md

@@ -1,9 +1,9 @@
 
 # lecousin.net - Java core framework
 
-The core library provides:
+The core library provides mainly:
  * A Multi-Threading framework, allowing asynchronous programming
- * A new IO (Input/Output) model, flexible, and providing asynchronous operations
+ * A new IO (Input/Output) model, much more flexible, and supporting asynchronous operations
 
 It does not have any dependency, however the library [net.lecousin.framework.system](https://github.com/lecousin/java-framework-system "java-framework-system")
 is recommended for better performances on disk operations (detection of physical drives).
@@ -20,33 +20,47 @@ Branch 0.9: ![build status](https://travis-ci.org/lecousin/java-framework-core.s
 
 ## Multi-threading
 
-The multi-threading system of this library is based on _physical_ resources for better performance:
+The multi-threading system is based on _physical_ resources for better performance:
  * One thread by available processor (CPU)
  * One thread by physical drive
 
 Each unit of work is a _Task_, that may succeed with a result, fail with an exception, or be cancelled.
 A task must use only one physical resource, so a process implying both CPU work and some operations on a drive
 must be split into several tasks.
 
+Because the multi-threading system allocates a single thread by CPU, if long running tasks are running, other
+tasks may wait for those tasks to finish if all CPUs are used. While this may be acceptable on a single application
+environment, it is recommended to split such long running tasks into smaller tasks. 
+
 A task should not, but is allowed to block. In this case the blocked thread is interrupted and a new thread
 is automatically launched to process other tasks for the same physical resource. Once the task is unblocked,
-the thread is resumed as soon as another thread is available and can be stopped.
-
-By default, the order tasks are executed is based on tasks' priority,
-then for the same priority in a first-in-first-out order.
-This may be changed by providing a new implementation of TaskPriorityManager.
+the thread is resumed as soon as another thread is available and can be stopped. For this, synchronized
+sections should be avoided as much as possible (or be very short), instead a _synchronization point_ should
+be used.
 
 Different kinds of _synchronization point_ are available in the package net.lecousin.framework.concurrent.synch,
 such as JoinPoint, SynchronizationPoint, AsyncWork... They allow to wait for one or more asynchronous operations
 to finish (successfully or not), by listening to them.
 
+By default, the order tasks are executed is based on tasks' priority,
+then for the same priority in a first-in-first-out order.
+This may be changed by providing a new implementation of TaskPriorityManager.
+
 ## IO Model
 
 The model provided by Java is very basic and mainly based on streams (reading or writing forward).
 
-Our model add two main additions:
- * Flexibility by using interfaces that define the capabilities of an Input/Output implementation such as Readable, Writable, Seekable, Resizable, Buffered...
- * Asynchronous operations allowing multi-threading
+Our model adds much more flexibility, by using interfaces that define the capabilities of an Input/Output
+implementation such as Readable, Writable, Seekable, Resizable, Buffered...
+By using those interfaces we can know which operations can be performed on an IO, but allow also a method
+to specify what are the minimum expected capabilities.
+
+For example a method that needs an IO on which it can write data, it can seek (move forward and backward),
+and it can resize the IO can be defined as follow:
+
+	public <T extends IO.Writable.Seekable & IO.Resizable> myMethod(T io) { ... }
+
+In addition, the model add asynchronous operations (non-blocking).
 
 ## Startup
 
@@ -60,13 +74,19 @@ as multiple applications may share the same environment, including the same mult
 
 ## Logging
 
-A logging system is also provided, in a similar way as other logging frameworks.
-TODO
+A logging system is also provided, in a similar way as other logging frameworks (using loggers and appenders).
 
-## Memory management
+The reason to provide again another logging system is to have a logging system capable to use our
+multi-threading system and asynchronous IO operations.
+
+Each time something is logged, this is done by using asynchronous operations and tasks such as the code
+logging information is not blocked to avoid reducing performance because of logging. 
 
-TODO
+## Memory management
 
-## Locale
+It often happens that data is kept in memory to improve performance, typically a cache. Such implementations
+can declare themselves to the MemoryManager. The MemoryManager is monitoring memory usage, so when available
+memory becomes low, it will ask the implementations to free some memory.
 
-TODO
+In addition, when an application is idle (doing almost nothing) since several minutes, the MemoryManager may
+decide to ask to free some memory to reduce the memory footprint of the application when it is idle.

net.lecousin.core/pom.xml

@@ -135,6 +135,9 @@
 						<goals>
 							<goal>jar</goal>
 						</goals>
+						<configuration>
+							<additionalparam>-Xdoclint:none</additionalparam>
+						</configuration>
 					</execution>
 				</executions>
 			</plugin>

net.lecousin.core/src/main/java/net/lecousin/framework/io/FragmentedSubIO.java

@@ -15,13 +15,12 @@
 
 /**
  * A fragmented sub-IO allows to specify a list of fragments inside a seekable IO, and does like those fragments are a contiguous IO.
- * TODO split it with Readable, Writable and ReadWrite
  * TODO improve perf by storing the fragment containing the current position ?
  */
-public class FragmentedSubIO extends IO.AbstractIO implements IO.Readable.Seekable, IO.KnownSize {
+public abstract class FragmentedSubIO extends IO.AbstractIO implements IO.KnownSize, IO.Seekable {
 
 	/** Constructor. */
-	public FragmentedSubIO(IO.Readable.Seekable io, List<RangeLong> fragments, boolean closeParentIOOnClose, String description) {
+	public FragmentedSubIO(IO.Seekable io, List<RangeLong> fragments, boolean closeParentIOOnClose, String description) {
 		this.io = io;
 		this.fragments = fragments;
 		this.closeParentIOOnClose = closeParentIOOnClose;
@@ -30,22 +29,85 @@ public FragmentedSubIO(IO.Readable.Seekable io, List<RangeLong> fragments, boole
 		for (RangeLong r : fragments) size += r.max - r.min + 1;
 	}
 
-	private IO.Readable.Seekable io;
-	private List<RangeLong> fragments;
-	private long pos = 0;
-	private long size;
-	private boolean closeParentIOOnClose;
-	private String description;
+	protected IO.Seekable io;
+	protected List<RangeLong> fragments;
+	protected long pos = 0;
+	protected long size;
+	protected boolean closeParentIOOnClose;
+	protected String description;
 
 	@Override
 	protected ISynchronizationPoint<IOException> closeIO() {
 		if (closeParentIOOnClose) return io.closeAsync();
 		return new SynchronizationPoint<>(true);
 	}
-	
-	@Override
-	public ISynchronizationPoint<IOException> canStartReading() {
-		return io.canStartReading();
+
+	/** Readable fragmented IO. */
+	public static class Readable extends FragmentedSubIO implements IO.Readable.Seekable {
+		
+		/** Constructor. */
+		public Readable(IO.Readable.Seekable io, List<RangeLong> fragments, boolean closeParentIOOnClose, String description) {
+			super(io, fragments, closeParentIOOnClose, description);
+		}
+
+		@Override
+		public ISynchronizationPoint<IOException> canStartReading() {
+			return ((IO.Readable.Seekable)io).canStartReading();
+		}
+		
+		@Override
+		public AsyncWork<Integer,IOException> readAsync(ByteBuffer buffer, RunnableWithParameter<Pair<Integer,IOException>> ondone) {
+			return super.readAsync(pos, buffer, ondone);
+		}
+
+		@Override
+		public AsyncWork<Integer, IOException> readAsync(
+			long pos, ByteBuffer buffer, RunnableWithParameter<Pair<Integer, IOException>> ondone
+		) {
+			return super.readAsync(pos, buffer, ondone);
+		}
+		
+		@Override
+		public int readSync(ByteBuffer buffer) throws IOException {
+			return super.readSync(pos, buffer);
+		}
+		
+		@Override
+		public int readSync(long pos, ByteBuffer buffer) throws IOException {
+			return super.readSync(pos, buffer);
+		}
+		
+		@Override
+		public int readFullySync(long pos, ByteBuffer buffer) throws IOException {
+			return super.readFullySync(pos, buffer);
+		}
+		
+		@Override
+		public int readFullySync(ByteBuffer buffer) throws IOException {
+			return super.readFullySync(pos, buffer);
+		}
+		
+		@Override
+		public AsyncWork<Integer,IOException> readFullyAsync(ByteBuffer buffer, RunnableWithParameter<Pair<Integer,IOException>> ondone) {
+			return readFullyAsync(pos, buffer, ondone);
+		}
+		
+		@Override
+		public AsyncWork<Integer,IOException> readFullyAsync(
+			long pos, ByteBuffer buffer, RunnableWithParameter<Pair<Integer,IOException>> ondone
+		) {
+			return IOUtil.readFullyAsynch(this, pos, buffer, ondone);
+		}
+		
+		@Override
+		public long skipSync(long n) {
+			return super.skipSync(n);
+		}
+		
+		@Override
+		public AsyncWork<Long, IOException> skipAsync(long n, RunnableWithParameter<Pair<Long, IOException>> ondone) {
+			return super.skipAsync(n, ondone);
+		}
 	}
 
 	@Override
@@ -90,13 +152,7 @@ public AsyncWork<Long, IOException> getSizeAsync() {
 		return sp;
 	}
 
-	@Override
-	public AsyncWork<Integer,IOException> readAsync(ByteBuffer buffer, RunnableWithParameter<Pair<Integer,IOException>> ondone) {
-		return readAsync(pos, buffer, ondone);
-	}
-	
-	@Override
-	public AsyncWork<Integer,IOException> readAsync(long pos, ByteBuffer buffer, RunnableWithParameter<Pair<Integer,IOException>> ondone) {
+	protected AsyncWork<Integer,IOException> readAsync(long pos, ByteBuffer buffer, RunnableWithParameter<Pair<Integer,IOException>> ondone) {
 		Iterator<RangeLong> it = fragments.iterator();
 		long p = 0;
 		while (it.hasNext()) {
@@ -111,7 +167,8 @@ public AsyncWork<Integer,IOException> readAsync(long pos, ByteBuffer buffer, Run
 			if (start + len > s) {
 				int prevLimit = buffer.limit();
 				buffer.limit((int)(prevLimit - ((start + len) - s)));
-				return io.readAsync(r.min + start, buffer, new RunnableWithParameter<Pair<Integer,IOException>>() {
+				return ((IO.Readable.Seekable)io).readAsync(r.min + start, buffer,
+				new RunnableWithParameter<Pair<Integer,IOException>>() {
 					@Override
 					public void run(Pair<Integer, IOException> param) {
 						buffer.limit(prevLimit);
@@ -121,7 +178,7 @@ public void run(Pair<Integer, IOException> param) {
 					}
 				});
 			}
-			return io.readAsync(r.min + start, buffer, new RunnableWithParameter<Pair<Integer,IOException>>() {
+			return ((IO.Readable.Seekable)io).readAsync(r.min + start, buffer, new RunnableWithParameter<Pair<Integer,IOException>>() {
 				@Override
 				public void run(Pair<Integer, IOException> param) {
 					if (param.getValue1() != null)
@@ -136,13 +193,7 @@ public void run(Pair<Integer, IOException> param) {
 		return sp;
 	}
 
-	@Override
-	public int readSync(ByteBuffer buffer) throws IOException {
-		return readSync(pos, buffer);
-	}
-	
-	@Override
-	public int readSync(long pos, ByteBuffer buffer) throws IOException {
+	protected int readSync(long pos, ByteBuffer buffer) throws IOException {
 		Iterator<RangeLong> it = fragments.iterator();
 		long p = 0;
 		while (it.hasNext()) {
@@ -157,24 +208,18 @@ public int readSync(long pos, ByteBuffer buffer) throws IOException {
 			if (start + len > s) {
 				int prevLimit = buffer.limit();
 				buffer.limit((int)(prevLimit - ((start + len) - s)));
-				len = io.readSync(r.min + start, buffer);
+				len = ((IO.Readable.Seekable)io).readSync(r.min + start, buffer);
 				buffer.limit(prevLimit);
 			} else {
-				len = io.readSync(r.min + start, buffer);
+				len = ((IO.Readable.Seekable)io).readSync(r.min + start, buffer);
 			}
 			this.pos = pos + len;
 			return len;
 		}
 		return 0;
 	}
 
-	@Override
-	public int readFullySync(ByteBuffer buffer) throws IOException {
-		return readFullySync(pos, buffer);
-	}
-	
-	@Override
-	public int readFullySync(long pos, ByteBuffer buffer) throws IOException {
+	protected int readFullySync(long pos, ByteBuffer buffer) throws IOException {
 		Iterator<RangeLong> it = fragments.iterator();
 		long p = 0;
 		int done = 0;
@@ -190,10 +235,10 @@ public int readFullySync(long pos, ByteBuffer buffer) throws IOException {
 			if (start + len > s) {
 				int prevLimit = buffer.limit();
 				buffer.limit((int)(prevLimit - ((start + len) - s)));
-				len = io.readFullySync(r.min + start, buffer);
+				len = ((IO.Readable.Seekable)io).readFullySync(r.min + start, buffer);
 				buffer.limit(prevLimit);
 			} else {
-				len = io.readFullySync(r.min + start, buffer);
+				len = ((IO.Readable.Seekable)io).readFullySync(r.min + start, buffer);
 			}
 			this.pos = pos + len;
 			done += len;
@@ -205,16 +250,6 @@ public int readFullySync(long pos, ByteBuffer buffer) throws IOException {
 		return done;
 	}
 
-	@Override
-	public AsyncWork<Integer,IOException> readFullyAsync(ByteBuffer buffer, RunnableWithParameter<Pair<Integer,IOException>> ondone) {
-		return readFullyAsync(pos, buffer, ondone);
-	}
-	
-	@Override
-	public AsyncWork<Integer,IOException> readFullyAsync(long pos, ByteBuffer buffer, RunnableWithParameter<Pair<Integer,IOException>> ondone) {
-		return IOUtil.readFullyAsynch(this, pos, buffer, ondone);
-	}
-	
 	@Override
 	public long seekSync(SeekType type, long move) {
 		switch (type) {
@@ -234,8 +269,7 @@ public long seekSync(SeekType type, long move) {
 		return pos;
 	}
 
-	@Override
-	public long skipSync(long n) {
+	protected long skipSync(long n) {
 		long size = getSizeSync();
 		// skip checkstyle: VariableDeclarationUsageDistance
 		long prevPos = pos;
@@ -254,8 +288,7 @@ public AsyncWork<Long,IOException> seekAsync(SeekType type, long move, RunnableW
 		return sp;
 	}
 
-	@Override
-	public AsyncWork<Long, IOException> skipAsync(long n, RunnableWithParameter<Pair<Long, IOException>> ondone) {
+	protected AsyncWork<Long, IOException> skipAsync(long n, RunnableWithParameter<Pair<Long, IOException>> ondone) {
 		AsyncWork<Long,IOException> sp = new AsyncWork<>();
 		long skipped = skipSync(n);
 		if (ondone != null) ondone.run(new Pair<>(Long.valueOf(skipped), null));

net.lecousin.core/src/test/java/net/lecousin/framework/core/tests/io/impl/TestFragmentedSubIOReadable.java

@@ -32,7 +32,7 @@ public TestFragmentedSubIOReadable(FragmentedFile f) {
 
 	@Override
 	protected IO.Readable createReadableFromFile(FileIO.ReadOnly file, long fileSize) {
-		return new FragmentedSubIO(file, f.fragments, true, "fragmented IO");
+		return new FragmentedSubIO.Readable(file, f.fragments, true, "fragmented IO");
 	}
 
 }

net.lecousin.core/src/test/java/net/lecousin/framework/core/tests/io/impl/TestFragmentedSubIOReadableSeekable.java

@@ -31,7 +31,7 @@ public TestFragmentedSubIOReadableSeekable(FragmentedFile f) {
 
 	@Override
 	protected IO.Readable.Seekable createReadableSeekableFromFile(ReadOnly file, long fileSize) throws Exception {
-		return new FragmentedSubIO(file, f.fragments, true, "fragmented IO");
+		return new FragmentedSubIO.Readable(file, f.fragments, true, "fragmented IO");
 	}
 
 }