Deal of the Day

Home » Main » Manning Forums » 2011 » The Well-Grounded Java Developer

Thread: Proposed changes to Chapter 2 - Feedback welcome!

Reply to this Thread Reply to this Thread Search Forum Search Forum Back to Thread List Back to Thread List

Permlink Replies: 6 - Pages: 1 - Last Post: Jun 11, 2012 11:41 AM by: martijn.verburg Threads: [ Previous | Next ]
martijn.verburg


Posts: 86
From: London
Registered: 1/26/11
Proposed changes to Chapter 2 - Feedback welcome!
Posted: Feb 19, 2011 9:07 AM
  Click to reply to this thread Reply

Hi all,

Alan Bateman who heads the NIO.2 team at Oracle kindly warned me that when build 130 of the JDK 7 comes out that NIO.2 will have some significant API changes.

With those changes coming on board and some other earlier feedback I've received, I'm proposing the following changes to Chapter 2 and I've love to hear your feedback on these.

* Alter the examples to show how NIO was done under Java 4 --> Java 6 vs NIO.2 in JDK 7, but I have to be mindful of page count here!

* An increased emphasis on Paths, e.g. How to access the components of a path, how to combine paths (with the resolve method), explain what normalize and relativize do (the latter being very useful when doing recursive operations for example) and some discussion on how to interoperate with existing code that uses java.io.File.

* Perhaps include an introduction section that quickly examples how Path and Files are used. Maybe a few simple examples, like showing how to read lines from file, eg:

Path path = Paths.get("logs", "access.log");
try (BufferedReader reader = Files.newBufferedReader(path, Charset.forName("UTF-8"))) {
String line;
while ((line = reader.readLine()) != null) {
...
}
}

* The easy-to-use Files.readAllLines and Files.readAllBytes are other examples of a quick start into using the API.

* Explicitly show how the open options are used to control how the file is opened or created (although the defaults will be fine for many cases). Include the static import to import java.nio.file.StandardOpenOption.* in the code samples so that the the examples are easier to read and less verbose. Same thing in other places, including the copy and move examples.

* Most applications won't need to use FileSystem and FileStore directly so maybe remove these?

* Another concept that isn't mentioned at present is that the API can be used to access files that aren't in the local file system. In jdk7 there is a provider for zip files for example. You can open a zip file with FileSystems.newFileSystem and use it to access the files in the zip file as if it were a file system. Would people want to see that?

* Listing 2-1 as it's not how the API should be used, this will have to change :-)

* On file attributes I'm suggesting starting with something a little more simple. I think that readers will have some familiarity with java.io.File so showing the equivalent might be a good start, ie: Files.{isDirectory,isRegularFile,isSymbolicLink,getLastModifiedTime,setLastModifiedTime}. I could also point out some newer methods like setOwner and getOwner.

* A good point that I might add; is that often you require several attributes of the same file at around the same time and this is why the API provides "bulk access" for groups of attributes.

* readBasicFileAttributes has been replaced by readAttributes where you specify a type token to select the attributes that you want, so this will change eg:

BasicFileAttributes attrs = Files.readAttributes(path, BasicFileAttributes.class);
PosixFileAttribtues attrs = Files.readAttributes(path, PosixFileAttributes.class);

* On file system specific attributes it could be good to point out the supportsFileAttributeView method as a quick way to check if the file system implementation supports access to these attributes. Would people want that covered?

* The section on symbolic links could be beefed up because symbolic links have implications through-out the API. An important point to make is that symbolic links are followed by default unless otherwise stated (examples where sym links aren't followed are delete and move). Methods that access file attributes have the LinkOption[] parameter to allow you specify if you want to access the attributes of the sym link or the final target. Do people want to see a more in depth coverage of symbolic links?

* The section on file change notification probably needs work. This might be seen as a relatively niche area of the API so an alternative is just to summarize the capabilities and not go into detail? This leaves more room for asynchronous I/O

* In the discussion about FileVisitor/SimpleFileVisitor it needs to be synced up with the build 130 version of jdk7 (preVisitDirectoryFailed was removed for example).

* The asynchronous I/O API could be an entire chapter in itself. So I really need to decide whether to sticking with AsynchronousFileChannel based examples or go with Network/Socket/Channel based examples. If I expand this section then it will require a more lengthy discussion on thread pools and channel groups. What would people prefer?

Cheers,
Martijn

z669016

Posts: 9
From: Netherlands
Registered: 7/11/07
Re: Proposed changes to Chapter 2 - Feedback welcome!
Posted: Feb 21, 2011 12:12 PM   in response to: martijn.verburg in response to: martijn.verburg
  Click to reply to this thread Reply

* Alter the examples to show how NIO was done under Java 4 --> Java 6 vs NIO.2 in JDK 7, but I have to be mindful of page count here!
> If you decide to compare the different NIO API’s from J2SE 1.4 through Java SE 7, I would only use it to show the how new insight/experience and design principles have influenced the development of the API over time. I think a full comparison would be out of scope, and quite frankly, not that interesting. An overview of Java IO including NIO2 and some exiting features (as it is now) was helpful to me.

* An increased emphasis on Paths, e.g. How to access the components of a path, how to combine paths (with the resolve method), explain what normalize and relativize do (the latter being very useful when doing recursive operations for example) and some discussion on how to interoperate with existing code that uses java.io.File.
> Nice (the combination of old- and new API), for the old API ain’t gone, is it?

* Perhaps include an introduction section that quickly examples how Path and Files are used. Maybe a few simple examples, like showing how to read lines from file, eg:

Path path = Paths.get("logs", "access.log");
try (BufferedReader reader = Files.newBufferedReader(path, Charset.forName("UTF-8"))) {
String line;
while ((line = reader.readLine()) != null) {
...
}
}

> With the increasing importance of character such a quick sample would be helpful

* The easy-to-use Files.readAllLines and Files.readAllBytes are other examples of a quick start into using the API.
> See previous remark

* Explicitly show how the open options are used to control how the file is opened or created (although the defaults will be fine for many cases). Include the static import to import java.nio.file.StandardOpenOption.* in the code samples so that the the examples are easier to read and less verbose. Same thing in other places, including the copy and move examples.
> Yes please

* Most applications won't need to use FileSystem and FileStore directly so maybe remove these?
> You could mention them as “advanced API’s” without going into further detail…

* Another concept that isn't mentioned at present is that the API can be used to access files that aren't in the local file system. In jdk7 there is a provider for zip files for example. You can open a zip file with FileSystems.newFileSystem and use it to access the files in the zip file as if it were a file system. Would people want to see that?
> I have struggled with zip/jar-files before, and they didn’t work very well. I have tried the Apache Commons Virtual File System once. It sounds like that features made it into the standard API?

* Listing 2-1 as it's not how the API should be used, this will have to change

* On file attributes I'm suggesting starting with something a little more simple. I think that readers will have some familiarity with java.io.File so showing the equivalent might be a good start, ie: Files.{isDirectory,isRegularFile,isSymbolicLink,getLastModifiedTime,setLastModifiedTime}. I could also point out some newer methods like setOwner and getOwner.
> If FileSystem and FileStore are rarely used, I would expect this to be quite rare also (in my case as an enterprise developer it is anyway).

* A good point that I might add; is that often you require several attributes of the same file at around the same time and this is why the API provides "bulk access" for groups of attributes.
> Only if you decide to address this (see point before this one).

* readBasicFileAttributes has been replaced by readAttributes where you specify a type token to select the attributes that you want, so this will change eg:

BasicFileAttributes attrs = Files.readAttributes(path, BasicFileAttributes.class);
PosixFileAttribtues attrs = Files.readAttributes(path, PosixFileAttributes.class);

> Well, I’m not so in favor of operating system specific issues myself….

* On file system specific attributes it could be good to point out the supportsFileAttributeView method as a quick way to check if the file system implementation supports access to these attributes. Would people want that covered?
> Not for me, thanks….

* The section on symbolic links could be beefed up because symbolic links have implications through-out the API. An important point to make is that symbolic links are followed by default unless otherwise stated (examples where sym links aren't followed are delete and move). Methods that access file attributes have the LinkOption[] parameter to allow you specify if you want to access the attributes of the sym link or the final target. Do people want to see a more in depth coverage of symbolic links?
> Does it impact basic I/O operations?

* The section on file change notification probably needs work. This might be seen as a relatively niche area of the API so an alternative is just to summarize the capabilities and not go into detail? This leaves more room for asynchronous I/O
> Details might be interesting for tool developers. I would prefer the summary of capabilities.

* In the discussion about FileVisitor/SimpleFileVisitor it needs to be synced up with the build 130 version of jdk7 (preVisitDirectoryFailed was removed for example).
> There is a lot on files, file systems, and file attributes….. How does this relate to the Java EE Spec’s who say not to use file-system api’s?

* The asynchronous I/O API could be an entire chapter in itself. So I really need to decide whether to sticking with AsynchronousFileChannel based examples or go with Network/Socket/Channel based examples. If I expand this section then it will require a more lengthy discussion on thread pools and channel groups. What would people prefer?
> Now this is interesting, for it provides insight in design decisions for high performance and concurrency. These issues are often underestimated. I would appreciate such a chapter.

martijn.verburg


Posts: 86
From: London
Registered: 1/26/11
Re: Proposed changes to Chapter 2 - Feedback welcome!
Posted: Feb 22, 2011 6:17 AM   in response to: z669016 in response to: z669016
  Click to reply to this thread Reply

Hi there,

Thanks for your detailed response! My further comments in line below

> * Alter the examples to show how NIO was done under
> Java 4 --> Java 6 vs NIO.2 in JDK 7, but I have to be
> mindful of page count here!
>
> > If you decide to compare the different NIO API’s
> > from J2SE 1.4 through Java SE 7, I would only use it
> > to show the how new insight/experience and design
> > principles have influenced the development of the API
> > over time. I think a full comparison would be out of
> > scope, and quite frankly, not that interesting. An
> > overview of Java IO including NIO2 and some exiting
> > features (as it is now) was helpful to me.

Fair call, I'll try to choose the appropriate times to do this.

> * Most applications won't need to use FileSystem and
> FileStore directly so maybe remove these?
> > You could mention them as “advanced API’s” without
> going into further detail…

I think I'll do just that.

> * Another concept that isn't mentioned at present is
> that the API can be used to access files that aren't
> in the local file system. In jdk7 there is a provider
> for zip files for example. You can open a zip file
> with FileSystems.newFileSystem and use it to access
> the files in the zip file as if it were a file
> system. Would people want to see that?
>
> > I have struggled with zip/jar-files before, and
> > they didn’t work very well. I have tried the Apache
> > Commons Virtual File System once. It sounds like that
> > features made it into the standard API?

Effectively yes, it's now part of the standard API.

> * The section on symbolic links could be beefed up
> because symbolic links have implications through-out
> the API. An important point to make is that symbolic
> links are followed by default unless otherwise stated
> (examples where sym links aren't followed are delete
> and move). Methods that access file attributes have
> the LinkOption[] parameter to allow you specify if
> you want to access the attributes of the sym link or
> the final target. Do people want to see a more in
> depth coverage of symbolic links?
> > Does it impact basic I/O operations?

Yes it does, knowing whether you are following or not following the symbolic links is pretty important for anyone working with the file system.

> * In the discussion about
> FileVisitor/SimpleFileVisitor it needs to be synced
> up with the build 130 version of jdk7
> (preVisitDirectoryFailed was removed for example).
>
> > There is a lot on files, file systems, and file
> > attributes….. How does this relate to the Java EE
> > Spec’s who say not to use file-system api’s?

Right, I think this (and your other comments) is highlighting a difference between the enterprise developer and a non-enterprise developer. The enterprise developer typically does not deal directly with the file system (if you're talking about enterprise being a JEE container-based application).

We will have to weigh up how much file system material to put in this Chapter as opposed to say Socket and Channel material. Even for the Asynch I/O Chapter it was suggested by members of the NIO.2 team that the file based examples would be easier to teach :-).

> * The asynchronous I/O API could be an entire chapter
> in itself. So I really need to decide whether to
> sticking with AsynchronousFileChannel based examples
> or go with Network/Socket/Channel based examples. If
> I expand this section then it will require a more
> lengthy discussion on thread pools and channel
> groups. What would people prefer?
>
> > Now this is interesting, for it provides insight in
> > design decisions for high performance and
> > concurrency. These issues are often underestimated. I
> > would appreciate such a chapter.

Once we have worked through the build 130 changes and restructured the chapter accordingly we will take a long hard look at whether we can fit in some extra material for this. The chapter (as it stands) could still be expanded by a few pages without making it overly large.

Thanks again,
Martijn

tpal

Posts: 1
Registered: 12/20/11
Re: Proposed changes to Chapter 2 - Feedback welcome!
Posted: Dec 20, 2011 12:14 PM   in response to: martijn.verburg in response to: martijn.verburg
  Click to reply to this thread Reply

Hi,

I might be wrong but wasn't the copyTo method removed from Path?

http://docs.oracle.com/javase/7/docs/api/java/nio/file/Path.html

Right now I can only find it (or its equivalent) in Files

http://docs.oracle.com/javase/7/docs/api/java/nio/file/Files.html

Thanks,

Tibor

dmarsh

Posts: 2
From: United Kingdom
Registered: 1/21/12
Re: Proposed changes to Chapter 2 - Feedback welcome!
Posted: Jan 21, 2012 12:00 PM   in response to: tpal in response to: tpal
  Click to reply to this thread Reply

Hello, I'm trying to work through the examples in my MEAP book and the code does not compile under Java 7. When are updated code examples that at least compile under Java 7 going to be available ?

I've downloaded the new examples source jar, which looks different so may compile. However it does not match my MEAP book and there are many comments like :-

* TODO When build 130 is released, this entire example will be redundant

What is 'build 130' ? It appears is is the Java 7 developer preview ? This was released on 23rd Feb 2011 ?

Java 7 is now six months old, the previews nearly a year old, when are we going to get real examples ?

many thanks

David

martijn.verburg


Posts: 86
From: London
Registered: 1/26/11
Re: Proposed changes to Chapter 2 - Feedback welcome!
Posted: Jun 11, 2012 11:40 AM   in response to: tpal in response to: tpal
  Click to reply to this thread Reply

Hi tpal,

This has been resolved in the API/book.

Cheers,
Martijn

martijn.verburg


Posts: 86
From: London
Registered: 1/26/11
Re: Proposed changes to Chapter 2 - Feedback welcome!
Posted: Jun 11, 2012 11:41 AM   in response to: dmarsh in response to: dmarsh
  Click to reply to this thread Reply

Hi David,

Apologies for missing this post - the code has been updated for the final release of Java 7, not sure if it got into the latest MEAP or not.

Cheers,
Martijn

Legend
Gold: 300 + pts
Silver: 100 - 299 pts
Bronze: 25 - 99 pts
Manning Author
Manning Staff
Manning Developmental Editor