archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-09-21 03:24:38 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

6781363: New I/O: Update socket-channel API to jsr203/nio2-b99

Browse source 
4313887: New I/O: Improved filesystem interface
4607272: New I/O: Support asynchronous I/O

Reviewed-by: sherman, chegar
This commit is contained in:
Alan Bateman 2009-02-15 12:25:54 +00:00
parent 68c4bef974
commit 030a13d8fe
364 changed files with 65095 additions and 1160 deletions
Download patch file Download diff file Expand all files Collapse all files

5
jdk/make/docs/CORE_PKGS.gmk
View file

@ -1,5 +1,5 @@
#
# Copyright 2001-2008 Sun Microsystems, Inc. All Rights Reserved.
# Copyright 2001-2009 Sun Microsystems, Inc. All Rights Reserved.
# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
#
# This code is free software; you can redistribute it and/or modify it
@ -110,6 +110,9 @@ CORE_PKGS = \
java.nio.channels.spi \
java.nio.charset \
java.nio.charset.spi \
java.nio.file \
java.nio.file.attribute \
java.nio.file.spi \
java.rmi \
java.rmi.activation \
java.rmi.dgc \

5
jdk/make/docs/NON_CORE_PKGS.gmk
View file

@ -1,5 +1,5 @@
#
# Copyright 2002-2008 Sun Microsystems, Inc. All Rights Reserved.
# Copyright 2002-2009 Sun Microsystems, Inc. All Rights Reserved.
# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
#
# This code is free software; you can redistribute it and/or modify it
@ -65,6 +65,8 @@ OLD_JSSE_PKGS = com.sun.net.ssl
HTTPSERVER_PKGS = com.sun.net.httpserver \
com.sun.net.httpserver.spi
NIO_PKGS = com.sun.nio.file
DOCLETAPI_PKGS = com.sun.javadoc
TAGLETAPI_FILE = com/sun/tools/doclets/Taglet.java
@ -92,6 +94,7 @@ NON_CORE_PKGS = $(DOMAPI_PKGS) \
$(MGMT_PKGS) \
$(JAAS_PKGS) \
$(JGSS_PKGS) \
$(NIO_PKGS) \
$(OLD_JSSE_PKGS) \
$(HTTPSERVER_PKGS) \
$(SMARTCARDIO_PKGS) \

4
jdk/make/java/nio/Exportedfiles.gmk
View file

@ -1,5 +1,5 @@
#
# Copyright 2000-2005 Sun Microsystems, Inc. All Rights Reserved.
# Copyright 2000-2009 Sun Microsystems, Inc. All Rights Reserved.
# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
#
# This code is free software; you can redistribute it and/or modify it
@ -33,7 +33,7 @@ FILES_export = \
sun/nio/ch/DatagramChannelImpl.java \
sun/nio/ch/DatagramDispatcher.java \
sun/nio/ch/FileChannelImpl.java \
sun/nio/ch/FileDispatcher.java \
sun/nio/ch/FileDispatcherImpl.java \
sun/nio/ch/FileKey.java \
sun/nio/ch/FileLockImpl.java \
sun/nio/ch/IOStatus.java \

4
jdk/make/java/nio/FILES_c.gmk
View file

@ -1,5 +1,5 @@
#
# Copyright 2000-2005 Sun Microsystems, Inc. All Rights Reserved.
# Copyright 2000-2009 Sun Microsystems, Inc. All Rights Reserved.
# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
#
# This code is free software; you can redistribute it and/or modify it
@ -27,7 +27,7 @@ FILES_c = \
DatagramChannelImpl.c \
DatagramDispatcher.c \
FileChannelImpl.c \
FileDispatcher.c \
FileDispatcherImpl.c \
FileKey.c \
IOUtil.c \
MappedByteBuffer.c \

137
jdk/make/java/nio/FILES_java.gmk
View file

@ -1,5 +1,5 @@
#
# Copyright 2000-2008 Sun Microsystems, Inc. All Rights Reserved.
# Copyright 2000-2009 Sun Microsystems, Inc. All Rights Reserved.
# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
#
# This code is free software; you can redistribute it and/or modify it
@ -31,19 +31,29 @@ FILES_src = \
java/nio/MappedByteBuffer.java \
java/nio/StringCharBuffer.java \
\
java/nio/channels/AsynchronousByteChannel.java \
java/nio/channels/AsynchronousChannel.java \
java/nio/channels/AsynchronousChannelGroup.java \
java/nio/channels/AsynchronousDatagramChannel.java \
java/nio/channels/AsynchronousFileChannel.java \
java/nio/channels/AsynchronousServerSocketChannel.java \
java/nio/channels/AsynchronousSocketChannel.java \
java/nio/channels/ByteChannel.java \
java/nio/channels/Channel.java \
java/nio/channels/Channels.java \
java/nio/channels/CompletionHandler.java \
java/nio/channels/DatagramChannel.java \
java/nio/channels/FileChannel.java \
java/nio/channels/FileLock.java \
java/nio/channels/GatheringByteChannel.java \
java/nio/channels/InterruptibleChannel.java \
java/nio/channels/Pipe.java \
java/nio/channels/MembershipKey.java \
java/nio/channels/MulticastChannel.java \
java/nio/channels/NetworkChannel.java \
java/nio/channels/ReadableByteChannel.java \
java/nio/channels/ScatteringByteChannel.java \
java/nio/channels/SeekableByteChannel.java \
java/nio/channels/SelectableChannel.java \
java/nio/channels/Selector.java \
java/nio/channels/SelectionKey.java \
@ -55,6 +65,7 @@ FILES_src = \
java/nio/channels/spi/AbstractSelectableChannel.java \
java/nio/channels/spi/AbstractSelectionKey.java \
java/nio/channels/spi/AbstractSelector.java \
java/nio/channels/spi/AsynchronousChannelProvider.java \
java/nio/channels/spi/SelectorProvider.java \
\
java/nio/charset/Charset.java \
@ -66,21 +77,117 @@ FILES_src = \
\
java/nio/charset/spi/CharsetProvider.java \
\
java/nio/file/AccessDeniedException.java \
java/nio/file/AccessMode.java \
java/nio/file/AtomicMoveNotSupportedException.java \
java/nio/file/ClosedDirectoryStreamException.java \
java/nio/file/ClosedFileSystemException.java \
java/nio/file/ClosedWatchServiceException.java \
java/nio/file/CopyOption.java \
java/nio/file/DirectoryNotEmptyException.java \
java/nio/file/DirectoryStream.java \
java/nio/file/DirectoryStreamFilters.java \
java/nio/file/FileAction.java \
java/nio/file/FileAlreadyExistsException.java \
java/nio/file/FileRef.java \
java/nio/file/FileStore.java \
java/nio/file/FileSystem.java \
java/nio/file/FileSystemAlreadyExistsException.java \
java/nio/file/FileSystemException.java \
java/nio/file/FileSystemNotFoundException.java \
java/nio/file/FileSystems.java \
java/nio/file/FileTreeWalker.java \
java/nio/file/FileVisitOption.java \
java/nio/file/FileVisitResult.java \
java/nio/file/FileVisitor.java \
java/nio/file/Files.java \
java/nio/file/InvalidPathException.java \
java/nio/file/LinkOption.java \
java/nio/file/LinkPermission.java \
java/nio/file/NoSuchFileException.java \
java/nio/file/NotDirectoryException.java \
java/nio/file/NotLinkException.java \
java/nio/file/OpenOption.java \
java/nio/file/Path.java \
java/nio/file/PathMatcher.java \
java/nio/file/Paths.java \
java/nio/file/ProviderMismatchException.java \
java/nio/file/ProviderNotFoundException.java \
java/nio/file/ReadOnlyFileSystemException.java \
java/nio/file/SecureDirectoryStream.java \
java/nio/file/SimpleFileVisitor.java \
java/nio/file/StandardCopyOption.java \
java/nio/file/StandardOpenOption.java \
java/nio/file/StandardWatchEventKind.java \
java/nio/file/WatchEvent.java \
java/nio/file/WatchKey.java \
java/nio/file/WatchService.java \
java/nio/file/Watchable.java \
\
java/nio/file/attribute/AclEntry.java \
java/nio/file/attribute/AclEntryFlag.java \
java/nio/file/attribute/AclEntryPermission.java \
java/nio/file/attribute/AclEntryType.java \
java/nio/file/attribute/AclFileAttributeView.java \
java/nio/file/attribute/AttributeView.java \
java/nio/file/attribute/Attributes.java \
java/nio/file/attribute/BasicFileAttributeView.java \
java/nio/file/attribute/BasicFileAttributes.java \
java/nio/file/attribute/DosFileAttributeView.java \
java/nio/file/attribute/DosFileAttributes.java \
java/nio/file/attribute/FileAttribute.java \
java/nio/file/attribute/FileAttributeView.java \
java/nio/file/attribute/FileOwnerAttributeView.java \
java/nio/file/attribute/FileStoreAttributeView.java \
java/nio/file/attribute/FileStoreSpaceAttributeView.java \
java/nio/file/attribute/FileStoreSpaceAttributes.java \
java/nio/file/attribute/GroupPrincipal.java \
java/nio/file/attribute/UserDefinedFileAttributeView.java \
java/nio/file/attribute/PosixFileAttributeView.java \
java/nio/file/attribute/PosixFileAttributes.java \
java/nio/file/attribute/PosixFilePermission.java \
java/nio/file/attribute/PosixFilePermissions.java \
java/nio/file/attribute/UserPrincipal.java \
java/nio/file/attribute/UserPrincipalLookupService.java \
java/nio/file/attribute/UserPrincipalNotFoundException.java \
\
java/nio/file/spi/AbstractPath.java \
java/nio/file/spi/FileSystemProvider.java \
java/nio/file/spi/FileTypeDetector.java \
\
com/sun/nio/file/ExtendedCopyOption.java \
com/sun/nio/file/ExtendedOpenOption.java \
com/sun/nio/file/ExtendedWatchEventModifier.java \
com/sun/nio/file/SensitivityWatchEventModifier.java \
\
sun/nio/ByteBuffered.java \
\
sun/nio/ch/AbstractFuture.java \
sun/nio/ch/AbstractPollArrayWrapper.java \
sun/nio/ch/AllocatedNativeObject.java \
sun/nio/ch/AsynchronousChannelGroupImpl.java \
sun/nio/ch/AsynchronousFileChannelImpl.java \
sun/nio/ch/AsynchronousServerSocketChannelImpl.java \
sun/nio/ch/AsynchronousSocketChannelImpl.java \
sun/nio/ch/Cancellable.java \
sun/nio/ch/ChannelInputStream.java \
sun/nio/ch/CompletedFuture.java \
sun/nio/ch/DatagramChannelImpl.java \
sun/nio/ch/DatagramDispatcher.java \
sun/nio/ch/DatagramSocketAdaptor.java \
sun/nio/ch/DefaultAsynchronousChannelProvider.java \
sun/nio/ch/DefaultSelectorProvider.java \
sun/nio/ch/DirectBuffer.java \
sun/nio/ch/ExtendedSocketOption.java \
sun/nio/ch/FileChannelImpl.java \
sun/nio/ch/FileDispatcher.java \
sun/nio/ch/FileDispatcherImpl.java \
sun/nio/ch/FileKey.java \
sun/nio/ch/FileLockImpl.java \
sun/nio/ch/FileLockTable.java \
sun/nio/ch/Groupable.java \
sun/nio/ch/Interruptible.java \
sun/nio/ch/Invoker.java \
sun/nio/ch/IOUtil.java \
sun/nio/ch/IOStatus.java \
sun/nio/ch/IOVecWrapper.java \
@ -92,6 +199,7 @@ FILES_src = \
sun/nio/ch/NativeThreadSet.java \
sun/nio/ch/Net.java \
sun/nio/ch/OptionKey.java \
sun/nio/ch/PendingFuture.java \
sun/nio/ch/PipeImpl.java \
sun/nio/ch/PollArrayWrapper.java \
sun/nio/ch/Reflect.java \
@ -101,12 +209,14 @@ FILES_src = \
sun/nio/ch/SelChImpl.java \
sun/nio/ch/ServerSocketAdaptor.java \
sun/nio/ch/ServerSocketChannelImpl.java \
sun/nio/ch/SimpleAsynchronousDatagramChannelImpl.java \
sun/nio/ch/SinkChannelImpl.java \
sun/nio/ch/SocketAdaptor.java \
sun/nio/ch/SocketChannelImpl.java \
sun/nio/ch/SocketDispatcher.java \
sun/nio/ch/SocketOptionRegistry.java \
sun/nio/ch/SourceChannelImpl.java \
sun/nio/ch/ThreadPool.java \
sun/nio/ch/Util.java \
\
sun/nio/cs/AbstractCharsetProvider.java \
@ -134,6 +244,24 @@ FILES_src = \
sun/nio/cs/UTF_32LE_BOM.java \
sun/nio/cs/UTF_32Coder.java \
\
sun/nio/fs/AbstractAclFileAttributeView.java \
sun/nio/fs/AbstractBasicFileAttributeView.java \
sun/nio/fs/AbstractFileStoreSpaceAttributeView.java \
sun/nio/fs/AbstractFileTypeDetector.java \
sun/nio/fs/AbstractPoller.java \
sun/nio/fs/AbstractUserDefinedFileAttributeView.java \
sun/nio/fs/AbstractWatchKey.java \
sun/nio/fs/AbstractWatchService.java \
sun/nio/fs/Cancellable.java \
sun/nio/fs/DefaultFileSystemProvider.java \
sun/nio/fs/DefaultFileTypeDetector.java \
sun/nio/fs/FileOwnerAttributeViewImpl.java \
sun/nio/fs/Globs.java \
sun/nio/fs/MimeType.java \
sun/nio/fs/NativeBuffer.java \
sun/nio/fs/NativeBuffers.java \
sun/nio/fs/Reflect.java \
\
java/net/DatagramSocket.java \
java/net/DatagramSocketImpl.java \
java/net/PlainSocketImpl.java \
@ -244,24 +372,31 @@ FILES_gen_ex = \
java/nio/InvalidMarkException.java \
java/nio/ReadOnlyBufferException.java \
\
java/nio/channels/AcceptPendingException.java \
java/nio/channels/AlreadyBoundException.java \
java/nio/channels/AlreadyConnectedException.java \
java/nio/channels/AsynchronousCloseException.java \
java/nio/channels/CancelledKeyException.java \
java/nio/channels/ClosedByInterruptException.java \
java/nio/channels/ClosedChannelException.java \
java/nio/channels/ClosedSelectorException.java \
java/nio/channels/ConnectionPendingException.java \
java/nio/channels/FileLockInterruptionException.java \
java/nio/channels/IllegalBlockingModeException.java \
java/nio/channels/IllegalChannelGroupException.java \
java/nio/channels/IllegalSelectorException.java \
java/nio/channels/InterruptedByTimeoutException.java \
java/nio/channels/NoConnectionPendingException.java \
java/nio/channels/NonReadableChannelException.java \
java/nio/channels/NonWritableChannelException.java \
java/nio/channels/NotYetBoundException.java \
java/nio/channels/NotYetConnectedException.java \
java/nio/channels/OverlappingFileLockException.java \
java/nio/channels/ReadPendingException.java \
java/nio/channels/ShutdownChannelGroupException.java \
java/nio/channels/UnresolvedAddressException.java \
java/nio/channels/UnsupportedAddressTypeException.java \
java/nio/channels/WritePendingException.java \
\
java/nio/charset/CharacterCodingException.java \
java/nio/charset/IllegalCharsetNameException.java \

214
jdk/make/java/nio/Makefile
View file

@ -1,5 +1,5 @@
#
# Copyright 2000-2008 Sun Microsystems, Inc. All Rights Reserved.
# Copyright 2000-2009 Sun Microsystems, Inc. All Rights Reserved.
# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
#
# This code is free software; you can redistribute it and/or modify it
@ -56,56 +56,214 @@ FILES_java += \
sun/nio/ch/DevPollSelectorProvider.java \
sun/nio/ch/InheritedChannel.java \
sun/nio/ch/PollSelectorProvider.java \
sun/nio/ch/PollSelectorImpl.java
sun/nio/ch/PollSelectorImpl.java \
sun/nio/ch/Port.java \
sun/nio/ch/SimpleAsynchronousFileChannelImpl.java \
sun/nio/ch/SolarisAsynchronousChannelProvider.java \
sun/nio/ch/SolarisEventPort.java \
sun/nio/ch/UnixAsynchronousServerSocketChannelImpl.java \
sun/nio/ch/UnixAsynchronousSocketChannelImpl.java \
\
sun/nio/fs/GnomeFileTypeDetector.java \
sun/nio/fs/PollingWatchService.java \
sun/nio/fs/SolarisAclFileAttributeView.java \
sun/nio/fs/SolarisFileStore.java \
sun/nio/fs/SolarisFileSystem.java \
sun/nio/fs/SolarisFileSystemProvider.java \
sun/nio/fs/SolarisUserDefinedFileAttributeView.java \
sun/nio/fs/SolarisNativeDispatcher.java \
sun/nio/fs/SolarisWatchService.java \
sun/nio/fs/UnixChannelFactory.java \
sun/nio/fs/UnixCopyFile.java \
sun/nio/fs/UnixDirectoryStream.java \
sun/nio/fs/UnixException.java \
sun/nio/fs/UnixFileAttributeViews.java \
sun/nio/fs/UnixFileAttributes.java \
sun/nio/fs/UnixFileKey.java \
sun/nio/fs/UnixFileModeAttribute.java \
sun/nio/fs/UnixFileStore.java \
sun/nio/fs/UnixFileStoreAttributes.java \
sun/nio/fs/UnixFileSystem.java \
sun/nio/fs/UnixFileSystemProvider.java \
sun/nio/fs/UnixMountEntry.java \
sun/nio/fs/UnixNativeDispatcher.java \
sun/nio/fs/UnixPath.java \
sun/nio/fs/UnixSecureDirectoryStream.java \
sun/nio/fs/UnixUriUtils.java \
sun/nio/fs/UnixUserPrincipals.java
FILES_c += \
DevPollArrayWrapper.c \
InheritedChannel.c \
NativeThread.c \
PollArrayWrapper.c
PollArrayWrapper.c \
SolarisEventPort.c \
UnixAsynchronousServerSocketChannelImpl.c \
UnixAsynchronousSocketChannelImpl.c \
\
GnomeFileTypeDetector.c \
SolarisNativeDispatcher.c \
SolarisWatchService.c \
UnixCopyFile.c \
UnixNativeDispatcher.c
FILES_export += \
sun/nio/ch/DevPollArrayWrapper.java \
sun/nio/ch/InheritedChannel.java \
sun/nio/ch/NativeThread.java
sun/nio/ch/NativeThread.java \
sun/nio/ch/SolarisEventPort.java \
sun/nio/ch/UnixAsynchronousServerSocketChannelImpl.java \
sun/nio/ch/UnixAsynchronousSocketChannelImpl.java \
\
sun/nio/fs/GnomeFileTypeDetector.java \
sun/nio/fs/SolarisNativeDispatcher.java \
sun/nio/fs/SolarisWatchService.java \
sun/nio/fs/UnixCopyFile.java \
sun/nio/fs/UnixNativeDispatcher.java
FILES_gen += \
sun/nio/fs/SolarisConstants.java \
sun/nio/fs/UnixConstants.java
endif # PLATFORM = solaris
ifeq ($(PLATFORM), windows)
FILES_java += \
sun/nio/ch/Iocp.java \
sun/nio/ch/PendingIoCache.java \
sun/nio/ch/WindowsAsynchronousChannelProvider.java \
sun/nio/ch/WindowsAsynchronousFileChannelImpl.java \
sun/nio/ch/WindowsAsynchronousServerSocketChannelImpl.java \
sun/nio/ch/WindowsAsynchronousSocketChannelImpl.java \
sun/nio/ch/WindowsSelectorImpl.java \
sun/nio/ch/WindowsSelectorProvider.java
sun/nio/ch/WindowsSelectorProvider.java \
\
sun/nio/fs/RegistryFileTypeDetector.java \
sun/nio/fs/WindowsAclFileAttributeView.java \
sun/nio/fs/WindowsChannelFactory.java \
sun/nio/fs/WindowsConstants.java \
sun/nio/fs/WindowsDirectoryStream.java \
sun/nio/fs/WindowsException.java \
sun/nio/fs/WindowsFileAttributeViews.java \
sun/nio/fs/WindowsFileAttributes.java \
sun/nio/fs/WindowsFileCopy.java \
sun/nio/fs/WindowsFileStore.java \
sun/nio/fs/WindowsFileSystem.java \
sun/nio/fs/WindowsFileSystemProvider.java \
sun/nio/fs/WindowsLinkSupport.java \
sun/nio/fs/WindowsUserDefinedFileAttributeView.java \
sun/nio/fs/WindowsNativeDispatcher.java \
sun/nio/fs/WindowsPath.java \
sun/nio/fs/WindowsPathParser.java \
sun/nio/fs/WindowsPathType.java \
sun/nio/fs/WindowsSecurity.java \
sun/nio/fs/WindowsSecurityDescriptor.java \
sun/nio/fs/WindowsUriSupport.java \
sun/nio/fs/WindowsUserPrincipals.java \
sun/nio/fs/WindowsWatchService.java
FILES_c += \
Iocp.c \
RegistryFileTypeDetector.c \
WindowsAsynchronousFileChannelImpl.c \
WindowsAsynchronousServerSocketChannelImpl.c \
WindowsAsynchronousSocketChannelImpl.c \
WindowsNativeDispatcher.c \
WindowsSelectorImpl.c
FILES_export += \
sun/nio/ch/WindowsSelectorImpl.java
sun/nio/ch/Iocp.java \
sun/nio/ch/WindowsAsynchronousFileChannelImpl.java \
sun/nio/ch/WindowsAsynchronousServerSocketChannelImpl.java \
sun/nio/ch/WindowsAsynchronousSocketChannelImpl.java \
sun/nio/ch/WindowsSelectorImpl.java \
sun/nio/fs/WindowsNativeDispatcher.java \
sun/nio/fs/RegistryFileTypeDetector.java
endif # PLATFORM = windows
ifeq ($(PLATFORM), linux)
FILES_java += \
sun/nio/ch/AbstractPollSelectorImpl.java \
sun/nio/ch/EPoll.java \
sun/nio/ch/EPollArrayWrapper.java \
sun/nio/ch/EPollPort.java \
sun/nio/ch/EPollSelectorProvider.java \
sun/nio/ch/EPollSelectorImpl.java \
sun/nio/ch/InheritedChannel.java \
sun/nio/ch/LinuxAsynchronousChannelProvider.java \
sun/nio/ch/PollSelectorProvider.java \
sun/nio/ch/PollSelectorImpl.java
sun/nio/ch/PollSelectorImpl.java \
sun/nio/ch/Port.java \
sun/nio/ch/SimpleAsynchronousFileChannelImpl.java \
sun/nio/ch/UnixAsynchronousServerSocketChannelImpl.java \
sun/nio/ch/UnixAsynchronousSocketChannelImpl.java \
\
sun/nio/fs/GnomeFileTypeDetector.java \
sun/nio/fs/LinuxDosFileAttributeView.java \
sun/nio/fs/LinuxFileStore.java \
sun/nio/fs/LinuxFileSystem.java \
sun/nio/fs/LinuxFileSystemProvider.java \
sun/nio/fs/LinuxUserDefinedFileAttributeView.java \
sun/nio/fs/LinuxNativeDispatcher.java \
sun/nio/fs/LinuxWatchService.java \
sun/nio/fs/PollingWatchService.java \
sun/nio/fs/UnixChannelFactory.java \
sun/nio/fs/UnixCopyFile.java \
sun/nio/fs/UnixDirectoryStream.java \
sun/nio/fs/UnixException.java \
sun/nio/fs/UnixFileAttributeViews.java \
sun/nio/fs/UnixFileAttributes.java \
sun/nio/fs/UnixFileKey.java \
sun/nio/fs/UnixFileModeAttribute.java \
sun/nio/fs/UnixFileStore.java \
sun/nio/fs/UnixFileStoreAttributes.java \
sun/nio/fs/UnixFileSystem.java \
sun/nio/fs/UnixFileSystemProvider.java \
sun/nio/fs/UnixMountEntry.java \
sun/nio/fs/UnixNativeDispatcher.java \
sun/nio/fs/UnixPath.java \
sun/nio/fs/UnixSecureDirectoryStream.java \
sun/nio/fs/UnixUriUtils.java \
sun/nio/fs/UnixUserPrincipals.java
FILES_c += \
EPoll.c \
EPollArrayWrapper.c \
EPollPort.c \
InheritedChannel.c \
NativeThread.c \
PollArrayWrapper.c
PollArrayWrapper.c \
UnixAsynchronousServerSocketChannelImpl.c \
UnixAsynchronousSocketChannelImpl.c \
\
GnomeFileTypeDetector.c \
LinuxNativeDispatcher.c \
LinuxWatchService.c \
UnixCopyFile.c \
UnixNativeDispatcher.c
FILES_export += \
sun/nio/ch/EPoll.java \
sun/nio/ch/EPollArrayWrapper.java \
sun/nio/ch/EPollPort.java \
sun/nio/ch/InheritedChannel.java \
sun/nio/ch/NativeThread.java
sun/nio/ch/NativeThread.java \
sun/nio/ch/UnixAsynchronousServerSocketChannelImpl.java \
sun/nio/ch/UnixAsynchronousSocketChannelImpl.java \
\
sun/nio/fs/GnomeFileTypeDetector.java \
sun/nio/fs/LinuxNativeDispatcher.java \
sun/nio/fs/LinuxWatchService.java \
sun/nio/fs/UnixCopyFile.java \
sun/nio/fs/UnixNativeDispatcher.java
FILES_gen += \
sun/nio/fs/UnixConstants.java
endif # PLATFORM = linux
#
# Find platform-specific C source files
#
vpath %.c $(PLATFORM_SRC)/native/sun/nio/fs
vpath %.c $(PLATFORM_SRC)/native/sun/nio/ch
vpath %.c $(SHARE_SRC)/native/sun/nio/ch
@ -175,12 +333,14 @@ CH_SRC=$(NIO_SRC)/channels
CS_SRC=$(NIO_SRC)/charset
SCH_SRC=$(SNIO_SRC)/ch
SCS_SRC=$(SNIO_SRC)/cs
SFS_SRC=$(SNIO_SRC)/fs
BUF_GEN=$(NIO_GEN)
CH_GEN=$(NIO_GEN)/channels
CS_GEN=$(NIO_GEN)/charset
SCH_GEN=$(SNIO_GEN)/ch
SCS_GEN=$(SNIO_GEN)/cs
SFS_GEN=$(SNIO_GEN)/fs
FILES_gensbcs_out = $(FILES_gen_sbcs:%.java=$(GENSRCDIR)/%.java)
@ -670,4 +830,40 @@ $(FILES_gensbcs_out): $(GENCSSRC)/SingleByte-X.java $(GENCSSRC)/sbcs
$(BOOT_JAVA_CMD) -cp $(CHARSETMAPPING_JARFILE) build.tools.charsetmapping.GenerateSBCS \
$(GENCSSRC) $(SCS_GEN) sbcs
#
# Generated file system implementation classes (Unix only)
#
GENUC_SRC = $(PLATFORM_SRC)/native/sun/nio/fs/genUnixConstants.c
GENUC_EXE = $(TEMPDIR)/genUnixConstants
GENUC_COPYRIGHT_YEARS = $(shell $(CAT) $(GENUC_SRC) | \
$(NAWK) '/^.*Copyright.*Sun/ { print $$3 }')
$(GENUC_EXE) : $(GENUC_SRC)
$(prep-target)
$(CC) $(CPPFLAGS) -o $@ $(GENUC_SRC)
$(SFS_GEN)/UnixConstants.java: $(GENUC_EXE)
$(prep-target)
NAWK="$(NAWK)" SH="$(SH)" $(SH) -e addNotices.sh $(GENUC_COPYRIGHT_YEARS) > $@
$(GENUC_EXE) >> $@
GENSC_SRC = $(PLATFORM_SRC)/native/sun/nio/fs/genSolarisConstants.c
GENSC_EXE = $(TEMPDIR)/genSolarisConstants
GENSC_COPYRIGHT_YEARS = $(shell $(CAT) $(GENSC_SRC) | \
$(NAWK) '/^.*Copyright.*Sun/ { print $$3 }')
$(GENSC_EXE) : $(GENSC_SRC)
$(prep-target)
$(CC) $(CPPFLAGS) -o $@ $(GENSC_SRC)
$(SFS_GEN)/SolarisConstants.java: $(GENSC_EXE)
$(prep-target)
NAWK="$(NAWK)" SH="$(SH)" $(SH) -e addNotices.sh $(GENSC_COPYRIGHT_YEARS) > $@
$(GENSC_EXE) >> $@
.PHONY: sources

113
jdk/make/java/nio/mapfile-linux
View file

@ -1,5 +1,5 @@
#
# Copyright 2001-2008 Sun Microsystems, Inc. All Rights Reserved.
# Copyright 2001-2009 Sun Microsystems, Inc. All Rights Reserved.
# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
#
# This code is free software; you can redistribute it and/or modify it
@ -44,27 +44,38 @@ SUNWprivate_1.1 {
Java_sun_nio_ch_EPollArrayWrapper_interrupt;
Java_sun_nio_ch_EPollArrayWrapper_offsetofData;
Java_sun_nio_ch_EPollArrayWrapper_sizeofEPollEvent;
Java_sun_nio_ch_EPoll_init;
Java_sun_nio_ch_EPoll_eventSize;
Java_sun_nio_ch_EPoll_eventsOffset;
Java_sun_nio_ch_EPoll_dataOffset;
Java_sun_nio_ch_EPoll_epollCreate;
Java_sun_nio_ch_EPoll_epollCtl;
Java_sun_nio_ch_EPoll_epollWait;
Java_sun_nio_ch_EPollPort_close0;
Java_sun_nio_ch_EPollPort_drain1;
Java_sun_nio_ch_EPollPort_interrupt;
Java_sun_nio_ch_EPollPort_socketpair;
Java_sun_nio_ch_FileChannelImpl_close0;
Java_sun_nio_ch_FileChannelImpl_force0;
Java_sun_nio_ch_FileChannelImpl_initIDs;
Java_sun_nio_ch_FileChannelImpl_lock0;
Java_sun_nio_ch_FileChannelImpl_map0;
Java_sun_nio_ch_FileChannelImpl_position0;
Java_sun_nio_ch_FileChannelImpl_release0;
Java_sun_nio_ch_FileChannelImpl_size0;
Java_sun_nio_ch_FileChannelImpl_transferTo0;
Java_sun_nio_ch_FileChannelImpl_truncate0;
Java_sun_nio_ch_FileChannelImpl_unmap0;
Java_sun_nio_ch_FileDispatcher_close0;
Java_sun_nio_ch_FileDispatcher_closeIntFD;
Java_sun_nio_ch_FileDispatcher_init;
Java_sun_nio_ch_FileDispatcher_preClose0;
Java_sun_nio_ch_FileDispatcher_pread0;
Java_sun_nio_ch_FileDispatcher_pwrite0;
Java_sun_nio_ch_FileDispatcher_read0;
Java_sun_nio_ch_FileDispatcher_readv0;
Java_sun_nio_ch_FileDispatcher_write0;
Java_sun_nio_ch_FileDispatcher_writev0;
Java_sun_nio_ch_FileDispatcherImpl_close0;
Java_sun_nio_ch_FileDispatcherImpl_closeIntFD;
Java_sun_nio_ch_FileDispatcherImpl_force0;
Java_sun_nio_ch_FileDispatcherImpl_init;
Java_sun_nio_ch_FileDispatcherImpl_lock0;
Java_sun_nio_ch_FileDispatcherImpl_preClose0;
Java_sun_nio_ch_FileDispatcherImpl_pread0;
Java_sun_nio_ch_FileDispatcherImpl_pwrite0;
Java_sun_nio_ch_FileDispatcherImpl_read0;
Java_sun_nio_ch_FileDispatcherImpl_readv0;
Java_sun_nio_ch_FileDispatcherImpl_release0;
Java_sun_nio_ch_FileDispatcherImpl_size0;
Java_sun_nio_ch_FileDispatcherImpl_truncate0;
Java_sun_nio_ch_FileDispatcherImpl_write0;
Java_sun_nio_ch_FileDispatcherImpl_writev0;
Java_sun_nio_ch_FileKey_init;
Java_sun_nio_ch_FileKey_initIDs;
Java_sun_nio_ch_InheritedChannel_close0;
@ -108,6 +119,76 @@ SUNWprivate_1.1 {
Java_sun_nio_ch_ServerSocketChannelImpl_accept0;
Java_sun_nio_ch_ServerSocketChannelImpl_initIDs;
Java_sun_nio_ch_SocketChannelImpl_checkConnect;
Java_sun_nio_ch_UnixAsynchronousServerSocketChannelImpl_accept0;
Java_sun_nio_ch_UnixAsynchronousServerSocketChannelImpl_initIDs;
Java_sun_nio_ch_UnixAsynchronousSocketChannelImpl_checkConnect;
Java_sun_nio_fs_GnomeFileTypeDetector_initializeGio;
Java_sun_nio_fs_GnomeFileTypeDetector_probeUsingGio;
Java_sun_nio_fs_GnomeFileTypeDetector_initializeGnomeVfs;
Java_sun_nio_fs_GnomeFileTypeDetector_probeUsingGnomeVfs;
Java_sun_nio_fs_LinuxWatchService_init;
Java_sun_nio_fs_LinuxWatchService_eventSize;
Java_sun_nio_fs_LinuxWatchService_eventOffsets;
Java_sun_nio_fs_LinuxWatchService_inotifyInit;
Java_sun_nio_fs_LinuxWatchService_inotifyAddWatch;
Java_sun_nio_fs_LinuxWatchService_inotifyRmWatch;
Java_sun_nio_fs_LinuxWatchService_configureBlocking;
Java_sun_nio_fs_LinuxWatchService_socketpair;
Java_sun_nio_fs_LinuxWatchService_poll;
Java_sun_nio_fs_LinuxNativeDispatcher_init;
Java_sun_nio_fs_LinuxNativeDispatcher_fgetxattr0;
Java_sun_nio_fs_LinuxNativeDispatcher_flistxattr;
Java_sun_nio_fs_LinuxNativeDispatcher_fsetxattr0;
Java_sun_nio_fs_LinuxNativeDispatcher_fremovexattr0;
Java_sun_nio_fs_LinuxNativeDispatcher_setmntent0;
Java_sun_nio_fs_LinuxNativeDispatcher_endmntent;
Java_sun_nio_fs_UnixNativeDispatcher_initIDs;
Java_sun_nio_fs_UnixNativeDispatcher_getcwd;
Java_sun_nio_fs_UnixNativeDispatcher_strerror;
Java_sun_nio_fs_UnixNativeDispatcher_dup;
Java_sun_nio_fs_UnixNativeDispatcher_access0;
Java_sun_nio_fs_UnixNativeDispatcher_stat0;
Java_sun_nio_fs_UnixNativeDispatcher_lstat0;
Java_sun_nio_fs_UnixNativeDispatcher_fstat;
Java_sun_nio_fs_UnixNativeDispatcher_fstatat0;
Java_sun_nio_fs_UnixNativeDispatcher_chmod0;
Java_sun_nio_fs_UnixNativeDispatcher_fchmod;
Java_sun_nio_fs_UnixNativeDispatcher_chown0;
Java_sun_nio_fs_UnixNativeDispatcher_lchown0;
Java_sun_nio_fs_UnixNativeDispatcher_fchown;
Java_sun_nio_fs_UnixNativeDispatcher_utimes0;
Java_sun_nio_fs_UnixNativeDispatcher_futimes;
Java_sun_nio_fs_UnixNativeDispatcher_open0;
Java_sun_nio_fs_UnixNativeDispatcher_openat0;
Java_sun_nio_fs_UnixNativeDispatcher_close;
Java_sun_nio_fs_UnixNativeDispatcher_read;
Java_sun_nio_fs_UnixNativeDispatcher_write;
Java_sun_nio_fs_UnixNativeDispatcher_fopen0;
Java_sun_nio_fs_UnixNativeDispatcher_fclose;
Java_sun_nio_fs_UnixNativeDispatcher_opendir0;
Java_sun_nio_fs_UnixNativeDispatcher_fdopendir;
Java_sun_nio_fs_UnixNativeDispatcher_readdir;
Java_sun_nio_fs_UnixNativeDispatcher_closedir;
Java_sun_nio_fs_UnixNativeDispatcher_link0;
Java_sun_nio_fs_UnixNativeDispatcher_unlink0;
Java_sun_nio_fs_UnixNativeDispatcher_unlinkat0;
Java_sun_nio_fs_UnixNativeDispatcher_rename0;
Java_sun_nio_fs_UnixNativeDispatcher_renameat0;
Java_sun_nio_fs_UnixNativeDispatcher_mkdir0;
Java_sun_nio_fs_UnixNativeDispatcher_rmdir0;
Java_sun_nio_fs_UnixNativeDispatcher_symlink0;
Java_sun_nio_fs_UnixNativeDispatcher_readlink0;
Java_sun_nio_fs_UnixNativeDispatcher_realpath0;
Java_sun_nio_fs_UnixNativeDispatcher_statvfs0;
Java_sun_nio_fs_UnixNativeDispatcher_pathconf0;
Java_sun_nio_fs_UnixNativeDispatcher_fpathconf;
Java_sun_nio_fs_UnixNativeDispatcher_mknod0;
Java_sun_nio_fs_UnixNativeDispatcher_getpwuid;
Java_sun_nio_fs_UnixNativeDispatcher_getgrgid;
Java_sun_nio_fs_UnixNativeDispatcher_getpwnam0;
Java_sun_nio_fs_UnixNativeDispatcher_getgrnam0;
Java_sun_nio_fs_UnixNativeDispatcher_getextmntent;
Java_sun_nio_fs_UnixCopyFile_transfer;
local:
*;

101
jdk/make/java/nio/mapfile-solaris
View file

@ -1,5 +1,5 @@
#
# Copyright 2001-2008 Sun Microsystems, Inc. All Rights Reserved.
# Copyright 2001-2009 Sun Microsystems, Inc. All Rights Reserved.
# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
#
# This code is free software; you can redistribute it and/or modify it
@ -43,26 +43,26 @@ SUNWprivate_1.1 {
Java_sun_nio_ch_DevPollArrayWrapper_register;
Java_sun_nio_ch_DevPollArrayWrapper_registerMultiple;
Java_sun_nio_ch_FileChannelImpl_close0;
Java_sun_nio_ch_FileChannelImpl_force0;
Java_sun_nio_ch_FileChannelImpl_initIDs;
Java_sun_nio_ch_FileChannelImpl_lock0;
Java_sun_nio_ch_FileChannelImpl_map0;
Java_sun_nio_ch_FileChannelImpl_position0;
Java_sun_nio_ch_FileChannelImpl_release0;
Java_sun_nio_ch_FileChannelImpl_size0;
Java_sun_nio_ch_FileChannelImpl_transferTo0;
Java_sun_nio_ch_FileChannelImpl_truncate0;
Java_sun_nio_ch_FileChannelImpl_unmap0;
Java_sun_nio_ch_FileDispatcher_close0;
Java_sun_nio_ch_FileDispatcher_closeIntFD;
Java_sun_nio_ch_FileDispatcher_init;
Java_sun_nio_ch_FileDispatcher_preClose0;
Java_sun_nio_ch_FileDispatcher_pread0;
Java_sun_nio_ch_FileDispatcher_pwrite0;
Java_sun_nio_ch_FileDispatcher_read0;
Java_sun_nio_ch_FileDispatcher_readv0;
Java_sun_nio_ch_FileDispatcher_write0;
Java_sun_nio_ch_FileDispatcher_writev0;
Java_sun_nio_ch_FileDispatcherImpl_close0;
Java_sun_nio_ch_FileDispatcherImpl_closeIntFD;
Java_sun_nio_ch_FileDispatcherImpl_force0;
Java_sun_nio_ch_FileDispatcherImpl_init;
Java_sun_nio_ch_FileDispatcherImpl_lock0;
Java_sun_nio_ch_FileDispatcherImpl_preClose0;
Java_sun_nio_ch_FileDispatcherImpl_pread0;
Java_sun_nio_ch_FileDispatcherImpl_pwrite0;
Java_sun_nio_ch_FileDispatcherImpl_read0;
Java_sun_nio_ch_FileDispatcherImpl_readv0;
Java_sun_nio_ch_FileDispatcherImpl_release0;
Java_sun_nio_ch_FileDispatcherImpl_size0;
Java_sun_nio_ch_FileDispatcherImpl_truncate0;
Java_sun_nio_ch_FileDispatcherImpl_write0;
Java_sun_nio_ch_FileDispatcherImpl_writev0;
Java_sun_nio_ch_FileKey_init;
Java_sun_nio_ch_FileKey_initIDs;
Java_sun_nio_ch_InheritedChannel_close0;
@ -106,6 +106,75 @@ SUNWprivate_1.1 {
Java_sun_nio_ch_ServerSocketChannelImpl_accept0;
Java_sun_nio_ch_ServerSocketChannelImpl_initIDs;
Java_sun_nio_ch_SocketChannelImpl_checkConnect;
Java_sun_nio_ch_UnixAsynchronousServerSocketChannelImpl_accept0;
Java_sun_nio_ch_UnixAsynchronousServerSocketChannelImpl_initIDs;
Java_sun_nio_ch_UnixAsynchronousSocketChannelImpl_checkConnect;
Java_sun_nio_ch_SolarisEventPort_init;
Java_sun_nio_ch_SolarisEventPort_portCreate;
Java_sun_nio_ch_SolarisEventPort_portClose;
Java_sun_nio_ch_SolarisEventPort_portAssociate;
Java_sun_nio_ch_SolarisEventPort_portGet;
Java_sun_nio_ch_SolarisEventPort_portGetn;
Java_sun_nio_ch_SolarisEventPort_portSend;
Java_sun_nio_fs_GnomeFileTypeDetector_initializeGio;
Java_sun_nio_fs_GnomeFileTypeDetector_probeUsingGio;
Java_sun_nio_fs_GnomeFileTypeDetector_initializeGnomeVfs;
Java_sun_nio_fs_GnomeFileTypeDetector_probeUsingGnomeVfs;
Java_sun_nio_fs_UnixNativeDispatcher_initIDs;
Java_sun_nio_fs_UnixNativeDispatcher_getcwd;
Java_sun_nio_fs_UnixNativeDispatcher_strerror;
Java_sun_nio_fs_UnixNativeDispatcher_dup;
Java_sun_nio_fs_UnixNativeDispatcher_access0;
Java_sun_nio_fs_UnixNativeDispatcher_stat0;
Java_sun_nio_fs_UnixNativeDispatcher_lstat0;
Java_sun_nio_fs_UnixNativeDispatcher_fstat;
Java_sun_nio_fs_UnixNativeDispatcher_fstatat0;
Java_sun_nio_fs_UnixNativeDispatcher_chmod0;
Java_sun_nio_fs_UnixNativeDispatcher_fchmod;
Java_sun_nio_fs_UnixNativeDispatcher_chown0;
Java_sun_nio_fs_UnixNativeDispatcher_lchown0;
Java_sun_nio_fs_UnixNativeDispatcher_fchown;
Java_sun_nio_fs_UnixNativeDispatcher_utimes0;
Java_sun_nio_fs_UnixNativeDispatcher_futimes;
Java_sun_nio_fs_UnixNativeDispatcher_open0;
Java_sun_nio_fs_UnixNativeDispatcher_openat0;
Java_sun_nio_fs_UnixNativeDispatcher_close;
Java_sun_nio_fs_UnixNativeDispatcher_read;
Java_sun_nio_fs_UnixNativeDispatcher_write;
Java_sun_nio_fs_UnixNativeDispatcher_fopen0;
Java_sun_nio_fs_UnixNativeDispatcher_fclose;
Java_sun_nio_fs_UnixNativeDispatcher_opendir0;
Java_sun_nio_fs_UnixNativeDispatcher_fdopendir;
Java_sun_nio_fs_UnixNativeDispatcher_readdir;
Java_sun_nio_fs_UnixNativeDispatcher_closedir;
Java_sun_nio_fs_UnixNativeDispatcher_link0;
Java_sun_nio_fs_UnixNativeDispatcher_unlink0;
Java_sun_nio_fs_UnixNativeDispatcher_unlinkat0;
Java_sun_nio_fs_UnixNativeDispatcher_rename0;
Java_sun_nio_fs_UnixNativeDispatcher_renameat0;
Java_sun_nio_fs_UnixNativeDispatcher_mkdir0;
Java_sun_nio_fs_UnixNativeDispatcher_rmdir0;
Java_sun_nio_fs_UnixNativeDispatcher_symlink0;
Java_sun_nio_fs_UnixNativeDispatcher_readlink0;
Java_sun_nio_fs_UnixNativeDispatcher_realpath0;
Java_sun_nio_fs_UnixNativeDispatcher_statvfs0;
Java_sun_nio_fs_UnixNativeDispatcher_pathconf0;
Java_sun_nio_fs_UnixNativeDispatcher_fpathconf;
Java_sun_nio_fs_UnixNativeDispatcher_mknod0;
Java_sun_nio_fs_UnixNativeDispatcher_getpwuid;
Java_sun_nio_fs_UnixNativeDispatcher_getgrgid;
Java_sun_nio_fs_UnixNativeDispatcher_getpwnam0;
Java_sun_nio_fs_UnixNativeDispatcher_getgrnam0;
Java_sun_nio_fs_UnixNativeDispatcher_getextmntent;
Java_sun_nio_fs_UnixCopyFile_transfer;
Java_sun_nio_fs_SolarisNativeDispatcher_init;
Java_sun_nio_fs_SolarisNativeDispatcher_facl;
Java_sun_nio_fs_SolarisWatchService_init;
Java_sun_nio_fs_SolarisWatchService_portCreate;
Java_sun_nio_fs_SolarisWatchService_portAssociate;
Java_sun_nio_fs_SolarisWatchService_portDissociate;
Java_sun_nio_fs_SolarisWatchService_portSend;
Java_sun_nio_fs_SolarisWatchService_portGetn;
local:
*;

4
jdk/make/mksample/nio/Makefile
View file

@ -1,5 +1,5 @@
#
# Copyright 2004-2008 Sun Microsystems, Inc. All Rights Reserved.
# Copyright 2004-2009 Sun Microsystems, Inc. All Rights Reserved.
# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
#
# This code is free software; you can redistribute it and/or modify it
@ -31,7 +31,7 @@ BUILDDIR = ../..
PRODUCT = java
include $(BUILDDIR)/common/Defs.gmk
SUBDIRS = multicast server
SUBDIRS = file multicast server
all build clean clobber::
$(SUBDIRS-loop)

56
jdk/make/mksample/nio/file/Makefile Normal file
View file

@ -0,0 +1,56 @@
#
# Copyright 2008-2009 Sun Microsystems, Inc. All Rights Reserved.
# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
#
# This code is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License version 2 only, as
# published by the Free Software Foundation. Sun designates this
# particular file as subject to the "Classpath" exception as provided
# by Sun in the LICENSE file that accompanied this code.
#
# This code is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
# version 2 for more details (a copy is included in the LICENSE file that
# accompanied this code).
#
# You should have received a copy of the GNU General Public License version
# 2 along with this work; if not, write to the Free Software Foundation,
# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
#
# Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
# CA 95054 USA or visit www.sun.com if you need additional information or
# have any questions.
#
#
# Makefile for the nio/file sample code
#
BUILDDIR = ../../..
PRODUCT = java
include $(BUILDDIR)/common/Defs.gmk
SAMPLE_SRC_DIR = $(SHARE_SRC)/sample/nio/file
SAMPLE_DST_DIR = $(SAMPLEDIR)/nio/file
SAMPLE_FILES = \
$(SAMPLE_DST_DIR)/AclEdit.java \
$(SAMPLE_DST_DIR)/Chmod.java \
$(SAMPLE_DST_DIR)/Copy.java \
$(SAMPLE_DST_DIR)/DiskUsage.java \
$(SAMPLE_DST_DIR)/FileType.java \
$(SAMPLE_DST_DIR)/WatchDir.java \
$(SAMPLE_DST_DIR)/Xdd.java
all build: $(SAMPLE_FILES)
$(SAMPLE_DST_DIR)/%: $(SAMPLE_SRC_DIR)/%
$(install-file)
clean clobber:
$(RM) -r $(SAMPLE_DST_DIR)
.PHONY: all build clean clobber

43
jdk/src/share/classes/com/sun/nio/file/ExtendedCopyOption.java Normal file
View file

@ -0,0 +1,43 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package com.sun.nio.file;
import java.nio.file.CopyOption;
/**
* Defines <em>extended</em> copy options supported on some platforms
* by Sun's provider implementation.
*
* @since 1.7
*/
public enum ExtendedCopyOption implements CopyOption {
/**
* The copy may be interrupted by the {@link Thread#interrupt interrupt}
* method.
*/
INTERRUPTIBLE,
}

50
jdk/src/share/classes/com/sun/nio/file/ExtendedOpenOption.java Normal file
View file

@ -0,0 +1,50 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package com.sun.nio.file;
import java.nio.file.OpenOption;
/**
* Defines <em>extended</em> open options supported on some platforms
* by Sun's provider implementation.
*
* @since 1.7
*/
public enum ExtendedOpenOption implements OpenOption {
/**
* Prevent operations on the file that request read access.
*/
NOSHARE_READ,
/**
* Prevent operations on the file that request write access.
*/
NOSHARE_WRITE,
/**
* Prevent operations on the file that request delete access.
*/
NOSHARE_DELETE;
}

43
jdk/src/share/classes/com/sun/nio/file/ExtendedWatchEventModifier.java Normal file
View file

@ -0,0 +1,43 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package com.sun.nio.file;
import java.nio.file.WatchEvent.Modifier;
/**
* Defines <em>extended</em> watch event modifiers supported on some platforms
* by Sun's provider implementation.
*
* @since 1.7
*/
public enum ExtendedWatchEventModifier implements Modifier {
/**
* Register a file tree instead of a single directory.
*/
FILE_TREE,
}

62
jdk/src/share/classes/com/sun/nio/file/SensitivityWatchEventModifier.java Normal file
View file

@ -0,0 +1,62 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package com.sun.nio.file;
import java.nio.file.WatchEvent.Modifier;
/**
* Defines the <em>sensitivity levels</em> when registering objects with a
* watch service implementation that polls the file system.
*
* @since 1.7
*/
public enum SensitivityWatchEventModifier implements Modifier {
/**
* High sensitivity.
*/
HIGH(2),
/**
* Medium sensitivity.
*/
MEDIUM(10),
/**
* Low sensitivity.
*/
LOW(30);
/**
* Returns the sensitivity in seconds.
*/
public int sensitivityValueInSeconds() {
return sensitivity;
}
private final int sensitivity;
private SensitivityWatchEventModifier(int sensitivity) {
this.sensitivity = sensitivity;
}
}

349
jdk/src/share/classes/java/io/File.java
View file

@ -1,5 +1,5 @@
/*
* Copyright 1994-2008 Sun Microsystems, Inc. All Rights Reserved.
* Copyright 1994-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -30,12 +30,12 @@ import java.net.URI;
import java.net.URL;
import java.net.MalformedURLException;
import java.net.URISyntaxException;
import java.util.ArrayList;
import java.util.Map;
import java.util.Hashtable;
import java.util.Random;
import java.util.*;
import java.nio.file.*;
import java.nio.file.attribute.*;
import java.security.AccessController;
import java.security.AccessControlException;
import java.security.PrivilegedAction;
import java.security.SecureRandom;
import sun.security.action.GetPropertyAction;
@ -131,6 +131,18 @@ import sun.security.action.GetPropertyAction;
* created, the abstract pathname represented by a <code>File</code> object
* will never change.
*
* <h4>Interoperability with {@code java.nio.file} package</h4>
*
* <p> The <a href="../../java/nio/file/package-summary.html">{@code java.nio.file}</a>
* package defines interfaces and classes for the Java virtual machine to access
* files, file attributes, and file systems. This API may be used to overcome
* many of the limitations of the {@code java.io.File} class.
* The {@link #toPath toPath} method may be used to obtain a {@link
* Path} that uses the abstract path represented by a {@code File} object to
* locate a file. The resulting {@code Path} provides more efficient and
* extensive access to file attributes, additional file operations, and I/O
* exceptions to help diagnose errors when an operation on a file fails.
*
* @author unascribed
* @since JDK1.0
*/
@ -573,6 +585,7 @@ public class File
* read access to the file
*
* @since JDK1.1
* @see Path#toRealPath
*/
public String getCanonicalPath() throws IOException {
return fs.canonicalize(fs.resolve(this));
@ -597,6 +610,7 @@ public class File
* read access to the file
*
* @since 1.2
* @see Path#toRealPath
*/
public File getCanonicalFile() throws IOException {
String canonPath = getCanonicalPath();
@ -663,6 +677,14 @@ public class File
* system is converted into an abstract pathname in a virtual machine on a
* different operating system.
*
* <p> Note that when this abstract pathname represents a UNC pathname then
* all components of the UNC (including the server name component) are encoded
* in the {@code URI} path. The authority component is undefined, meaning
* that it is represented as {@code null}. The {@link Path} class defines the
* {@link Path#toUri toUri} method to encode the server name in the authority
* component of the resulting {@code URI}. The {@link #toPath toPath} method
* may be used to obtain a {@code Path} representing this abstract pathname.
*
* @return An absolute, hierarchical URI with a scheme equal to
* <tt>"file"</tt>, a path representing this abstract pathname,
* and undefined authority, query, and fragment components
@ -764,6 +786,8 @@ public class File
* If a security manager exists and its <code>{@link
* java.lang.SecurityManager#checkRead(java.lang.String)}</code>
* method denies read access to the file
*
* @see Attributes#readBasicFileAttributes
*/
public boolean isDirectory() {
SecurityManager security = System.getSecurityManager();
@ -788,6 +812,8 @@ public class File
* If a security manager exists and its <code>{@link
* java.lang.SecurityManager#checkRead(java.lang.String)}</code>
* method denies read access to the file
*
* @see Attributes#readBasicFileAttributes
*/
public boolean isFile() {
SecurityManager security = System.getSecurityManager();
@ -836,6 +862,8 @@ public class File
* If a security manager exists and its <code>{@link
* java.lang.SecurityManager#checkRead(java.lang.String)}</code>
* method denies read access to the file
*
* @see Attributes#readBasicFileAttributes
*/
public long lastModified() {
SecurityManager security = System.getSecurityManager();
@ -858,6 +886,8 @@ public class File
* If a security manager exists and its <code>{@link
* java.lang.SecurityManager#checkRead(java.lang.String)}</code>
* method denies read access to the file
*
* @see Attributes#readBasicFileAttributes
*/
public long length() {
SecurityManager security = System.getSecurityManager();
@ -907,6 +937,12 @@ public class File
* this pathname denotes a directory, then the directory must be empty in
* order to be deleted.
*
* <p> Note that the {@link Path} class defines the {@link Path#delete
* delete} method to throw an {@link IOException} when a file cannot be
* deleted. This is useful for error reporting and to diagnose why a file
* cannot be deleted. The {@link #toPath toPath} method may be used to
* obtain a {@code Path} representing this abstract pathname.
*
* @return <code>true</code> if and only if the file or directory is
* successfully deleted; <code>false</code> otherwise
*
@ -973,6 +1009,13 @@ public class File
* will appear in any specific order; they are not, in particular,
* guaranteed to appear in alphabetical order.
*
* <p> Note that the {@link Path} class defines the {@link
* Path#newDirectoryStream newDirectoryStream} method to open a directory
* and iterate over the names of the files in the directory. This may use
* less resources when working with very large directories. The {@link
* #toPath toPath} method may be used to obtain a {@code Path} representing
* this abstract pathname.
*
* @return An array of strings naming the files and directories in the
* directory denoted by this abstract pathname. The array will be
* empty if the directory is empty. Returns {@code null} if
@ -1024,13 +1067,13 @@ public class File
if ((names == null) || (filter == null)) {
return names;
}
ArrayList v = new ArrayList();
List<String> v = new ArrayList<String>();
for (int i = 0 ; i < names.length ; i++) {
if (filter.accept(this, names[i])) {
v.add(names[i]);
}
}
return (String[])(v.toArray(new String[v.size()]));
return v.toArray(new String[v.size()]);
}
/**
@ -1052,6 +1095,13 @@ public class File
* will appear in any specific order; they are not, in particular,
* guaranteed to appear in alphabetical order.
*
* <p> Note that the {@link Path} class defines the {@link
* Path#newDirectoryStream newDirectoryStream} method to open a directory
* and iterate over the names of the files in the directory. This may use
* less resources when working with very large directories. The {@link
* #toPath toPath} method may be used to obtain a {@code Path} representing
* this abstract pathname.
*
* @return An array of abstract pathnames denoting the files and
* directories in the directory denoted by this abstract pathname.
* The array will be empty if the directory is empty. Returns
@ -1157,6 +1207,12 @@ public class File
/**
* Creates the directory named by this abstract pathname.
*
* <p> Note that the {@link Path} class defines the {@link Path#createDirectory
* createDirectory} method to throw an {@link IOException} when a directory
* cannot be created. This is useful for error reporting and to diagnose why
* a directory cannot be created. The {@link #toPath toPath} method may be
* used to obtain a {@code Path} representing this abstract pathname.
*
* @return <code>true</code> if and only if the directory was
* created; <code>false</code> otherwise
*
@ -1222,6 +1278,11 @@ public class File
* already exists. The return value should always be checked to make sure
* that the rename operation was successful.
*
* <p> Note that the {@link Path} class defines the {@link Path#moveTo
* moveTo} method to move or rename a file in a platform independent manner.
* The {@link #toPath toPath} method may be used to obtain a {@code Path}
* representing this abstract pathname.
*
* @param dest The new abstract pathname for the named file
*
* @return <code>true</code> if and only if the renaming succeeded;
@ -1304,10 +1365,14 @@ public class File
return fs.setReadOnly(this);
}
/**
/**
* Sets the owner's or everybody's write permission for this abstract
* pathname.
*
* <p> The {@link Attributes Attributes} class defines methods that operate
* on file attributes including file permissions. This may be used when
* finer manipulation of file permissions is required.
*
* @param writable
* If <code>true</code>, sets the access permission to allow write
* operations; if <code>false</code> to disallow write operations
@ -1371,6 +1436,10 @@ public class File
* Sets the owner's or everybody's read permission for this abstract
* pathname.
*
* <p> The {@link Attributes Attributes} class defines methods that operate
* on file attributes including file permissions. This may be used when
* finer manipulation of file permissions is required.
*
* @param readable
* If <code>true</code>, sets the access permission to allow read
* operations; if <code>false</code> to disallow read operations
@ -1440,6 +1509,10 @@ public class File
* Sets the owner's or everybody's execute permission for this abstract
* pathname.
*
* <p> The {@link Attributes Attributes} class defines methods that operate
* on file attributes including file permissions. This may be used when
* finer manipulation of file permissions is required.
*
* @param executable
* If <code>true</code>, sets the access permission to allow execute
* operations; if <code>false</code> to disallow execute operations
@ -1678,44 +1751,44 @@ public class File
/* -- Temporary files -- */
private static final Object tmpFileLock = new Object();
private static class TemporaryDirectory {
private TemporaryDirectory() { }
private static int counter = -1; /* Protected by tmpFileLock */
static final String valueAsString = fs.normalize(
AccessController.doPrivileged(new GetPropertyAction("java.io.tmpdir")));
static final File valueAsFile =
new File(valueAsString, fs.prefixLength(valueAsString));
private static File generateFile(String prefix, String suffix, File dir)
throws IOException
{
if (counter == -1) {
counter = new Random().nextInt() & 0xffff;
}
counter++;
return new File(dir, prefix + Integer.toString(counter) + suffix);
}
private static String tmpdir; /* Protected by tmpFileLock */
private static String getTempDir() {
if (tmpdir == null)
tmpdir = fs.normalize(
AccessController.doPrivileged(
new GetPropertyAction("java.io.tmpdir")));
return tmpdir;
}
private static boolean checkAndCreate(String filename, SecurityManager sm)
throws IOException
{
if (sm != null) {
try {
sm.checkWrite(filename);
} catch (AccessControlException x) {
/* Throwing the original AccessControlException could disclose
the location of the default temporary directory, so we
re-throw a more innocuous SecurityException */
throw new SecurityException("Unable to create temporary file");
// file name generation
private static final SecureRandom random = new SecureRandom();
static File generateFile(String prefix, String suffix, File dir) {
long n = random.nextLong();
if (n == Long.MIN_VALUE) {
n = 0; // corner case
} else {
n = Math.abs(n);
}
return new File(dir, prefix + Long.toString(n) + suffix);
}
// default file permissions
static final FileAttribute<Set<PosixFilePermission>> defaultPosixFilePermissions =
PosixFilePermissions.asFileAttribute(EnumSet
.of(PosixFilePermission.OWNER_READ, PosixFilePermission.OWNER_WRITE));
static final boolean isPosix = isPosix();
static boolean isPosix() {
return AccessController.doPrivileged(
new PrivilegedAction<Boolean>() {
public Boolean run() {
try {
return FileSystems.getDefault().getPath(valueAsString)
.getFileStore().supportsFileAttributeView("posix");
} catch (IOException e) {
throw new IOError(e);
}
}
});
}
return fs.createFileExclusively(filename);
}
/**
@ -1791,22 +1864,29 @@ public class File
File directory)
throws IOException
{
if (prefix == null) throw new NullPointerException();
if (prefix.length() < 3)
throw new IllegalArgumentException("Prefix string too short");
String s = (suffix == null) ? ".tmp" : suffix;
synchronized (tmpFileLock) {
if (directory == null) {
String tmpDir = getTempDir();
directory = new File(tmpDir, fs.prefixLength(tmpDir));
if (suffix == null)
suffix = ".tmp";
File tmpdir = (directory != null) ?
directory : TemporaryDirectory.valueAsFile;
SecurityManager sm = System.getSecurityManager();
File f;
do {
f = TemporaryDirectory.generateFile(prefix, suffix, tmpdir);
if (sm != null) {
try {
sm.checkWrite(f.getPath());
} catch (SecurityException se) {
// don't reveal temporary directory location
if (directory == null)
throw new SecurityException("Unable to create temporary file");
throw se;
}
}
SecurityManager sm = System.getSecurityManager();
File f;
do {
f = generateFile(prefix, s, directory);
} while (!checkAndCreate(f.getPath(), sm));
return f;
}
} while (!fs.createFileExclusively(f.getPath()));
return f;
}
/**
@ -1844,6 +1924,122 @@ public class File
return createTempFile(prefix, suffix, null);
}
/**
* Creates an empty file in the default temporary-file directory, using
* the given prefix and suffix to generate its name. This method is
* equivalent to invoking the {@link #createTempFile(String,String)
* createTempFile(prefix,&nbsp;suffix)} method with the addition that the
* resulting pathname may be requested to be deleted when the Java virtual
* machine terminates, and the initial file attributes to set atomically
* when creating the file may be specified.
*
* <p> When the value of the {@code deleteOnExit} method is {@code true}
* then the resulting file is requested to be deleted when the Java virtual
* machine terminates as if by invoking the {@link #deleteOnExit deleteOnExit}
* method.
*
* <p> The {@code attrs} parameter is an optional array of {@link FileAttribute
* attributes} to set atomically when creating the file. Each attribute is
* identified by its {@link FileAttribute#name name}. If more than one attribute
* of the same name is included in the array then all but the last occurrence
* is ignored.
*
* @param prefix
* The prefix string to be used in generating the file's
* name; must be at least three characters long
* @param suffix
* The suffix string to be used in generating the file's
* name; may be {@code null}, in which case the suffix
* {@code ".tmp"} will be used
* @param deleteOnExit
* {@code true} if the file denoted by resulting pathname be
* deleted when the Java virtual machine terminates
* @param attrs
* An optional list of file attributes to set atomically when creating
* the file
*
* @return An abstract pathname denoting a newly-created empty file
*
* @throws IllegalArgumentException
* If the <code>prefix</code> argument contains fewer than three
* characters
* @throws UnsupportedOperationException
* If the array contains an attribute that cannot be set atomically
* when creating the file
* @throws IOException
* If a file could not be created
* @throws SecurityException
* If a security manager exists and its <code>{@link
* java.lang.SecurityManager#checkWrite(java.lang.String)}</code>
* method does not allow a file to be created. When the {@code
* deleteOnExit} parameter has the value {@code true} then the
* security manager's {@link
* java.lang.SecurityManager#checkDelete(java.lang.String)} is
* invoked to check delete access to the file.
* @since 1.7
*/
public static File createTempFile(String prefix,
String suffix,
boolean deleteOnExit,
FileAttribute<?>... attrs)
throws IOException
{
if (prefix.length() < 3)
throw new IllegalArgumentException("Prefix string too short");
suffix = (suffix == null) ? ".tmp" : suffix;
// special case POSIX environments so that 0600 is used as the file mode
if (TemporaryDirectory.isPosix) {
if (attrs.length == 0) {
// no attributes so use default permissions
attrs = new FileAttribute<?>[1];
attrs[0] = TemporaryDirectory.defaultPosixFilePermissions;
} else {
// check if posix permissions given; if not use default
boolean hasPermissions = false;
for (int i=0; i<attrs.length; i++) {
if (attrs[i].name().equals("posix:permissions")) {
hasPermissions = true;
break;
}
}
if (!hasPermissions) {
FileAttribute<?>[] copy = new FileAttribute<?>[attrs.length+1];
System.arraycopy(attrs, 0, copy, 0, attrs.length);
attrs = copy;
attrs[attrs.length-1] =
TemporaryDirectory.defaultPosixFilePermissions;
}
}
}
// use Path#createFile to create file
SecurityManager sm = System.getSecurityManager();
for (;;) {
File f = TemporaryDirectory
.generateFile(prefix, suffix, TemporaryDirectory.valueAsFile);
if (sm != null && deleteOnExit)
sm.checkDelete(f.getPath());
try {
f.toPath().createFile(attrs);
if (deleteOnExit)
DeleteOnExitHook.add(f.getPath());
return f;
} catch (InvalidPathException e) {
// don't reveal temporary directory location
if (sm != null)
throw new IllegalArgumentException("Invalid prefix or suffix");
throw e;
} catch (SecurityException e) {
// don't reveal temporary directory location
if (sm != null)
throw new SecurityException("Unable to create temporary file");
throw e;
} catch (FileAlreadyExistsException e) {
// ignore
}
}
}
/* -- Basic infrastructure -- */
@ -1963,5 +2159,46 @@ public class File
);
}
// -- Integration with java.nio.file --
private volatile transient Path filePath;
/**
* Returns a {@link Path java.nio.file.Path} object constructed from the
* this abstract path. The first invocation of this method works as if
* invoking it were equivalent to evaluating the expression:
* <blockquote><pre>
* {@link FileSystems#getDefault FileSystems.getDefault}().{@link FileSystem#getPath getPath}(this.{@link #getPath getPath}());
* </pre></blockquote>
* Subsequent invocations of this method return the same {@code Path}.
*
* <p> If this abstract pathname is the empty abstract pathname then this
* method returns a {@code Path} that may be used to access to the current
* user directory.
*
* @return A {@code Path} constructed from this abstract path. The resulting
* {@code Path} is associated with the {@link FileSystems#getDefault
* default-filesystem}.
*
* @throws InvalidPathException
* If a {@code Path} object cannot be constructed from the abstract
* path (see {@link java.nio.file.FileSystem#getPath FileSystem.getPath})
*
* @since 1.7
*/
public Path toPath() {
if (filePath == null) {
synchronized (this) {
if (filePath == null) {
if (path.length() == 0) {
// assume default file system treats "." as current directory
filePath = Paths.get(".");
} else {
filePath = Paths.get(path);
}
}
}
}
return filePath;
}
}

58
jdk/src/share/classes/java/io/FilePermission.java
View file

@ -1,5 +1,5 @@
/*
* Copyright 1997-2005 Sun Microsystems, Inc. All Rights Reserved.
* Copyright 1997-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -29,7 +29,6 @@ import java.security.*;
import java.util.Enumeration;
import java.util.List;
import java.util.ArrayList;
import java.util.StringTokenizer;
import java.util.Vector;
import java.util.Collections;
import java.io.ObjectStreamField;
@ -58,7 +57,8 @@ import sun.security.util.SecurityConstants;
* <P>
* The actions to be granted are passed to the constructor in a string containing
* a list of one or more comma-separated keywords. The possible keywords are
* "read", "write", "execute", and "delete". Their meaning is defined as follows:
* "read", "write", "execute", "delete", and "readlink". Their meaning is
* defined as follows:
* <P>
* <DL>
* <DT> read <DD> read permission
@ -69,6 +69,11 @@ import sun.security.util.SecurityConstants;
* <DT> delete
* <DD> delete permission. Allows <code>File.delete</code> to
* be called. Corresponds to <code>SecurityManager.checkDelete</code>.
* <DT> readlink
* <DD> read link permission. Allows the target of a
* <a href="../nio/file/package-summary.html#links">symbolic link</a>
* to be read by invoking the {@link java.nio.file.Path#readSymbolicLink
* readSymbolicLink } method.
* </DL>
* <P>
* The actions string is converted to lowercase before processing.
@ -114,11 +119,15 @@ public final class FilePermission extends Permission implements Serializable {
* Delete action.
*/
private final static int DELETE = 0x8;
/**
* Read link action.
*/
private final static int READLINK = 0x10;
/**
* All actions (read,write,execute,delete)
* All actions (read,write,execute,delete,readlink)
*/
private final static int ALL = READ|WRITE|EXECUTE|DELETE;
private final static int ALL = READ|WRITE|EXECUTE|DELETE|READLINK;
/**
* No actions.
*/
@ -235,7 +244,7 @@ public final class FilePermission extends Permission implements Serializable {
* <i>path</i> is the pathname of a file or directory, and <i>actions</i>
* contains a comma-separated list of the desired actions granted on the
* file or directory. Possible actions are
* "read", "write", "execute", and "delete".
* "read", "write", "execute", "delete", and "readlink".
*
* <p>A pathname that ends in "/*" (where "/" is
* the file separator character, <code>File.separatorChar</code>)
@ -425,6 +434,8 @@ public final class FilePermission extends Permission implements Serializable {
return EXECUTE;
} else if (actions == SecurityConstants.FILE_DELETE_ACTION) {
return DELETE;
} else if (actions == SecurityConstants.FILE_READLINK_ACTION) {
return READLINK;
}
char[] a = actions.toCharArray();
@ -485,6 +496,18 @@ public final class FilePermission extends Permission implements Serializable {
matchlen = 6;
mask |= DELETE;
} else if (i >= 7 && (a[i-7] == 'r' || a[i-7] == 'R') &&
(a[i-6] == 'e' || a[i-6] == 'E') &&
(a[i-5] == 'a' || a[i-5] == 'A') &&
(a[i-4] == 'd' || a[i-4] == 'D') &&
(a[i-3] == 'l' || a[i-3] == 'L') &&
(a[i-2] == 'i' || a[i-2] == 'I') &&
(a[i-1] == 'n' || a[i-1] == 'N') &&
(a[i] == 'k' || a[i] == 'K'))
{
matchlen = 8;
mask |= READLINK;
} else {
// parse error
throw new IllegalArgumentException(
@ -529,7 +552,7 @@ public final class FilePermission extends Permission implements Serializable {
/**
* Return the canonical string representation of the actions.
* Always returns present actions in the following order:
* read, write, execute, delete.
* read, write, execute, delete, readlink.
*
* @return the canonical string representation of the actions.
*/
@ -561,14 +584,20 @@ public final class FilePermission extends Permission implements Serializable {
sb.append("delete");
}
if ((mask & READLINK) == READLINK) {
if (comma) sb.append(',');
else comma = true;
sb.append("readlink");
}
return sb.toString();
}
/**
* Returns the "canonical string representation" of the actions.
* That is, this method always returns present actions in the following order:
* read, write, execute, delete. For example, if this FilePermission object
* allows both write and read actions, a call to <code>getActions</code>
* read, write, execute, delete, readlink. For example, if this FilePermission
* object allows both write and read actions, a call to <code>getActions</code>
* will return the string "read,write".
*
* @return the canonical string representation of the actions.
@ -678,7 +707,7 @@ final class FilePermissionCollection extends PermissionCollection
implements Serializable {
// Not serialized; see serialization section at end of class
private transient List perms;
private transient List<Permission> perms;
/**
* Create an empty FilePermissions object.
@ -686,7 +715,7 @@ implements Serializable {
*/
public FilePermissionCollection() {
perms = new ArrayList();
perms = new ArrayList<Permission>();
}
/**
@ -791,7 +820,7 @@ implements Serializable {
// Don't call out.defaultWriteObject()
// Write out Vector
Vector permissions = new Vector(perms.size());
Vector<Permission> permissions = new Vector<Permission>(perms.size());
synchronized (this) {
permissions.addAll(perms);
}
@ -804,6 +833,7 @@ implements Serializable {
/*
* Reads in a Vector of FilePermissions and saves them in the perms field.
*/
@SuppressWarnings("unchecked")
private void readObject(ObjectInputStream in) throws IOException,
ClassNotFoundException {
// Don't call defaultReadObject()
@ -812,8 +842,8 @@ implements Serializable {
ObjectInputStream.GetField gfields = in.readFields();
// Get the one we want
Vector permissions = (Vector)gfields.get("permissions", null);
perms = new ArrayList(permissions.size());
Vector<Permission> permissions = (Vector<Permission>)gfields.get("permissions", null);
perms = new ArrayList<Permission>(permissions.size());
perms.addAll(permissions);
}
}

4
jdk/src/share/classes/java/net/StandardProtocolFamily.java
View file

@ -1,5 +1,5 @@
/*
* Copyright 2007-2008 Sun Microsystems, Inc. All Rights Reserved.
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -26,7 +26,7 @@
package java.net;
/**
* Defines the standard family of communication protocols.
* Defines the standard families of communication protocols.
*
* @since 1.7
*/

39
jdk/src/share/classes/java/net/StandardSocketOption.java
View file

@ -1,5 +1,5 @@
/*
* Copyright 2007-2008 Sun Microsystems, Inc. All Rights Reserved.
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -59,6 +59,7 @@ public final class StandardSocketOption {
*
* @see <a href="http://www.ietf.org/rfc/rfc919.txt">RFC&nbsp;929:
* Broadcasting Internet Datagrams</a>
* @see DatagramSocket#setBroadcast
*/
public static final SocketOption<Boolean> SO_BROADCAST =
new StdSocketOption<Boolean>("SO_BROADCAST", Boolean.class);
@ -78,6 +79,7 @@ public final class StandardSocketOption {
*
* @see <a href="http://www.ietf.org/rfc/rfc1122.txt">RFC&nbsp;1122
* Requirements for Internet Hosts -- Communication Layers</a>
* @see Socket#setKeepAlive
*/
public static final SocketOption<Boolean> SO_KEEPALIVE =
new StdSocketOption<Boolean>("SO_KEEPALIVE", Boolean.class);
@ -107,6 +109,8 @@ public final class StandardSocketOption {
* socket is bound or connected. Whether an implementation allows the
* socket send buffer to be changed after the socket is bound is system
* dependent.
*
* @see Socket#setSendBufferSize
*/
public static final SocketOption<Integer> SO_SNDBUF =
new StdSocketOption<Integer>("SO_SNDBUF", Integer.class);
@ -145,6 +149,8 @@ public final class StandardSocketOption {
*
* @see <a href="http://www.ietf.org/rfc/rfc1323.txt">RFC&nbsp;1323: TCP
* Extensions for High Performance</a>
* @see Socket#setReceiveBufferSize
* @see ServerSocket#setReceiveBufferSize
*/
public static final SocketOption<Integer> SO_RCVBUF =
new StdSocketOption<Integer>("SO_RCVBUF", Integer.class);
@ -175,6 +181,7 @@ public final class StandardSocketOption {
*
* @see <a href="http://www.ietf.org/rfc/rfc793.txt">RFC&nbsp;793: Transmission
* Control Protocol</a>
* @see ServerSocket#setReuseAddress
*/
public static final SocketOption<Boolean> SO_REUSEADDR =
new StdSocketOption<Boolean>("SO_REUSEADDR", Boolean.class);
@ -205,6 +212,8 @@ public final class StandardSocketOption {
* is system dependent. Setting the linger interval to a value that is
* greater than its maximum value causes the linger interval to be set to
* its maximum value.
*
* @see Socket#setSoLinger
*/
public static final SocketOption<Integer> SO_LINGER =
new StdSocketOption<Integer>("SO_LINGER", Integer.class);
@ -215,15 +224,15 @@ public final class StandardSocketOption {
/**
* The Type of Service (ToS) octet in the Internet Protocol (IP) header.
*
* <p> The value of this socket option is an {@code Integer}, the least
* significant 8 bits of which represents the value of the ToS octet in IP
* packets sent by sockets to an {@link StandardProtocolFamily#INET IPv4}
* socket. The interpretation of the ToS octet is network specific and
* is not defined by this class. Further information on the ToS octet can be
* found in <a href="http://www.ietf.org/rfc/rfc1349.txt">RFC&nbsp;1349</a>
* and <a href="http://www.ietf.org/rfc/rfc2474.txt">RFC&nbsp;2474</a>. The
* value of the socket option is a <em>hint</em>. An implementation may
* ignore the value, or ignore specific values.
* <p> The value of this socket option is an {@code Integer} representing
* the value of the ToS octet in IP packets sent by sockets to an {@link
* StandardProtocolFamily#INET IPv4} socket. The interpretation of the ToS
* octet is network specific and is not defined by this class. Further
* information on the ToS octet can be found in <a
* href="http://www.ietf.org/rfc/rfc1349.txt">RFC&nbsp;1349</a> and <a
* href="http://www.ietf.org/rfc/rfc2474.txt">RFC&nbsp;2474</a>. The value
* of the socket option is a <em>hint</em>. An implementation may ignore the
* value, or ignore specific values.
*
* <p> The initial/default value of the TOS field in the ToS octet is
* implementation specific but will typically be {@code 0}. For
@ -235,6 +244,8 @@ public final class StandardSocketOption {
* <p> The behavior of this socket option on a stream-oriented socket, or an
* {@link StandardProtocolFamily#INET6 IPv6} socket, is not defined in this
* release.
*
* @see DatagramSocket#setTrafficClass
*/
public static final SocketOption<Integer> IP_TOS =
new StdSocketOption<Integer>("IP_TOS", Integer.class);
@ -257,6 +268,7 @@ public final class StandardSocketOption {
* is system dependent.
*
* @see java.nio.channels.MulticastChannel
* @see MulticastSocket#setInterface
*/
public static final SocketOption<NetworkInterface> IP_MULTICAST_IF =
new StdSocketOption<NetworkInterface>("IP_MULTICAST_IF", NetworkInterface.class);
@ -283,6 +295,7 @@ public final class StandardSocketOption {
* prior to binding the socket is system dependent.
*
* @see java.nio.channels.MulticastChannel
* @see MulticastSocket#setTimeToLive
*/
public static final SocketOption<Integer> IP_MULTICAST_TTL =
new StdSocketOption<Integer>("IP_MULTICAST_TTL", Integer.class);
@ -307,6 +320,7 @@ public final class StandardSocketOption {
* binding the socket is system dependent.
*
* @see java.nio.channels.MulticastChannel
* @see MulticastSocket#setLoopbackMode
*/
public static final SocketOption<Boolean> IP_MULTICAST_LOOP =
new StdSocketOption<Boolean>("IP_MULTICAST_LOOP", Boolean.class);
@ -328,11 +342,12 @@ public final class StandardSocketOption {
* coalescing impacts performance. The socket option may be enabled at any
* time. In other words, the Nagle Algorithm can be disabled. Once the option
* is enabled, it is system dependent whether it can be subsequently
* disabled. In that case, invoking the {@code setOption} method to disable
* the option has no effect.
* disabled. If it cannot, then invoking the {@code setOption} method to
* disable the option has no effect.
*
* @see <a href="http://www.ietf.org/rfc/rfc1122.txt">RFC&nbsp;1122:
* Requirements for Internet Hosts -- Communication Layers</a>
* @see Socket#setTcpNoDelay
*/
public static final SocketOption<Boolean> TCP_NODELAY =
new StdSocketOption<Boolean>("TCP_NODELAY", Boolean.class);

205
jdk/src/share/classes/java/nio/channels/AsynchronousByteChannel.java Normal file
View file

@ -0,0 +1,205 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.channels;
import java.nio.ByteBuffer;
import java.util.concurrent.Future;
/**
* An asynchronous channel that can read and write bytes.
*
* <p> Some channels may not allow more than one read or write to be outstanding
* at any given time. If a thread invokes a read method before a previous read
* operation has completed then a {@link ReadPendingException} will be thrown.
* Similarly, if a write method is invoked before a previous write has completed
* then {@link WritePendingException} is thrown. Whether or not other kinds of
* I/O operations may proceed concurrently with a read operation depends upon
* the type of the channel.
*
* <p> Note that {@link java.nio.ByteBuffer ByteBuffers} are not safe for use by
* multiple concurrent threads. When a read or write operation is initiated then
* care must be taken to ensure that the buffer is not accessed until the
* operation completes.
*
* @see Channels#newInputStream(AsynchronousByteChannel)
* @see Channels#newOutputStream(AsynchronousByteChannel)
*
* @since 1.7
*/
public interface AsynchronousByteChannel
extends AsynchronousChannel
{
/**
* Reads a sequence of bytes from this channel into the given buffer.
*
* <p> This method initiates an operation to read a sequence of bytes from
* this channel into the given buffer. The method returns a {@link Future}
* representing the pending result of the operation. The result of the
* operation, obtained by invoking the {@code Future} 's {@link
* Future#get() get} method, is the number of bytes read or {@code -1} if
* all bytes have been read and the channel has reached end-of-stream.
*
* <p> This method initiates a read operation to read up to <i>r</i> bytes
* from the channel, where <i>r</i> is the number of bytes remaining in the
* buffer, that is, {@code dst.remaining()} at the time that the read is
* attempted. Where <i>r</i> is 0, the read operation completes immediately
* with a result of {@code 0} without initiating an I/O operation.
*
* <p> Suppose that a byte sequence of length <i>n</i> is read, where
* <tt>0</tt>&nbsp;<tt>&lt;</tt>&nbsp;<i>n</i>&nbsp;<tt>&lt;=</tt>&nbsp;<i>r</i>.
* This byte sequence will be transferred into the buffer so that the first
* byte in the sequence is at index <i>p</i> and the last byte is at index
* <i>p</i>&nbsp;<tt>+</tt>&nbsp;<i>n</i>&nbsp;<tt>-</tt>&nbsp;<tt>1</tt>,
* where <i>p</i> is the buffer's position at the moment the read is
* performed. Upon completion the buffer's position will be equal to
* <i>p</i>&nbsp;<tt>+</tt>&nbsp;<i>n</i>; its limit will not have changed.
*
* <p> Buffers are not safe for use by multiple concurrent threads so care
* should be taken to not to access the buffer until the operaton has completed.
*
* <p> This method may be invoked at any time. Some channel types may not
* allow more than one read to be outstanding at any given time. If a thread
* initiates a read operation before a previous read operation has
* completed then a {@link ReadPendingException} will be thrown.
*
* <p> The <tt>handler</tt> parameter is used to specify a {@link
* CompletionHandler}. When the read operation completes the handler's
* {@link CompletionHandler#completed completed} method is executed.
*
*
* @param dst
* The buffer into which bytes are to be transferred
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
* The completion handler object; can be {@code null}
*
* @return A Future representing the result of the operation
*
* @throws IllegalArgumentException
* If the buffer is read-only
* @throws ReadPendingException
* If the channel does not allow more than one read to be outstanding
* and a previous read has not completed
*/
<A> Future<Integer> read(ByteBuffer dst,
A attachment,
CompletionHandler<Integer,? super A> handler);
/**
* Reads a sequence of bytes from this channel into the given buffer.
*
* <p> An invocation of this method of the form <tt>c.read(dst)</tt>
* behaves in exactly the same manner as the invocation
* <blockquote><pre>
* c.read(dst, null, null);</pre></blockquote>
*
* @param dst
* The buffer into which bytes are to be transferred
*
* @return A Future representing the result of the operation
*
* @throws IllegalArgumentException
* If the buffer is read-only
* @throws ReadPendingException
* If the channel does not allow more than one read to be outstanding
* and a previous read has not completed
*/
Future<Integer> read(ByteBuffer dst);
/**
* Writes a sequence of bytes to this channel from the given buffer.
*
* <p> This method initiates an operation to write a sequence of bytes to
* this channel from the given buffer. This method returns a {@link
* Future} representing the pending result of the operation. The result
* of the operation, obtained by invoking the <tt>Future</tt>'s {@link
* Future#get() get} method, is the number of bytes written, possibly zero.
*
* <p> This method initiates a write operation to write up to <i>r</i> bytes
* to the channel, where <i>r</i> is the number of bytes remaining in the
* buffer, that is, {@code src.remaining()} at the moment the write is
* attempted. Where <i>r</i> is 0, the write operation completes immediately
* with a result of {@code 0} without initiating an I/O operation.
*
* <p> Suppose that a byte sequence of length <i>n</i> is written, where
* <tt>0</tt>&nbsp;<tt>&lt;</tt>&nbsp;<i>n</i>&nbsp;<tt>&lt;=</tt>&nbsp;<i>r</i>.
* This byte sequence will be transferred from the buffer starting at index
* <i>p</i>, where <i>p</i> is the buffer's position at the moment the
* write is performed; the index of the last byte written will be
* <i>p</i>&nbsp;<tt>+</tt>&nbsp;<i>n</i>&nbsp;<tt>-</tt>&nbsp;<tt>1</tt>.
* Upon completion the buffer's position will be equal to
* <i>p</i>&nbsp;<tt>+</tt>&nbsp;<i>n</i>; its limit will not have changed.
*
* <p> Buffers are not safe for use by multiple concurrent threads so care
* should be taken to not to access the buffer until the operaton has completed.
*
* <p> This method may be invoked at any time. Some channel types may not
* allow more than one write to be outstanding at any given time. If a thread
* initiates a write operation before a previous write operation has
* completed then a {@link WritePendingException} will be thrown.
*
* <p> The <tt>handler</tt> parameter is used to specify a {@link
* CompletionHandler}. When the write operation completes the handler's
* {@link CompletionHandler#completed completed} method is executed.
*
* @param src
* The buffer from which bytes are to be retrieved
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
* The completion handler object; can be {@code null}
*
* @return A Future representing the result of the operation
*
* @throws WritePendingException
* If the channel does not allow more than one write to be outstanding
* and a previous write has not completed
*/
<A> Future<Integer> write(ByteBuffer src,
A attachment,
CompletionHandler<Integer,? super A> handler);
/**
* Writes a sequence of bytes to this channel from the given buffer.
*
* <p> An invocation of this method of the form <tt>c.write(src)</tt>
* behaves in exactly the same manner as the invocation
* <blockquote><pre>
* c.write(src, null, null);</pre></blockquote>
*
* @param src
* The buffer from which bytes are to be retrieved
*
* @return A Future representing the result of the operation
*
* @throws WritePendingException
* If the channel does not allow more than one write to be outstanding
* and a previous write has not completed
*/
Future<Integer> write(ByteBuffer src);
}

116
jdk/src/share/classes/java/nio/channels/AsynchronousChannel.java Normal file
View file

@ -0,0 +1,116 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.channels;
import java.io.IOException;
import java.util.concurrent.Future; // javadoc
/**
* A channel that supports asynchronous I/O operations. Asynchronous I/O
* operations will usually take one of two forms:
*
* <ol>
* <li><pre>{@link Future}&lt;V&gt; <em>operation</em>(<em>...</em>)</pre></li>
* <li><pre>Future&lt;V&gt; <em>operation</em>(<em>...</em> A attachment, {@link CompletionHandler}&lt;V,? super A&gt handler)</pre></li>
* </ol>
*
* where <i>operation</i> is the name of the I/O operation (read or write for
* example), <i>V</i> is the result type of the I/O operation, and <i>A</i> is
* the type of an object attached to the I/O operation to provide context when
* consuming the result. The attachment is important for cases where a
* <em>state-less</em> {@code CompletionHandler} is used to consume the result
* of many I/O operations.
*
* <p> In the first form, the methods defined by the {@link Future Future}
* interface may be used to check if the operation has completed, wait for its
* completion, and to retrieve the result. In the second form, a {@link
* CompletionHandler} is invoked to consume the result of the I/O operation when
* it completes, fails, or is cancelled.
*
* <p> A channel that implements this interface is <em>asynchronously
* closeable</em>: If an I/O operation is outstanding on the channel and the
* channel's {@link #close close} method is invoked, then the I/O operation
* fails with the exception {@link AsynchronousCloseException}.
*
* <p> Asynchronous channels are safe for use by multiple concurrent threads.
* Some channel implementations may support concurrent reading and writing, but
* may not allow more than one read and one write operation to be outstanding at
* any given time.
*
* <h4>Cancellation</h4>
*
* <p> The {@code Future} interface defines the {@link Future#cancel cancel}
* method to cancel execution of a task.
*
* <p> Where the {@code cancel} method is invoked with the {@code
* mayInterruptIfRunning} parameter set to {@code true} then the I/O operation
* may be interrupted by closing the channel. This will cause any other I/O
* operations outstanding on the channel to complete with the exception {@link
* AsynchronousCloseException}.
*
* <p> If a {@code CompletionHandler} is specified when initiating an I/O
* operation, and the {@code cancel} method is invoked to cancel the I/O
* operation before it completes, then the {@code CompletionHandler}'s {@link
* CompletionHandler#cancelled cancelled} method is invoked.
*
* <p> If an implementation of this interface supports a means to cancel I/O
* operations, and where cancellation may leave the channel, or the entity to
* which it is connected, in an inconsistent state, then the channel is put into
* an implementation specific <em>error state</em> that prevents further
* attempts to initiate I/O operations on the channel. For example, if a read
* operation is cancelled but the implementation cannot guarantee that bytes
* have not been read from the channel then it puts the channel into error state
* state; further attempts to initiate a {@code read} operation causes an
* unspecified runtime exception to be thrown.
*
* <p> Where the {@code cancel} method is invoked to cancel read or write
* operations then it recommended that all buffers used in the I/O operations be
* discarded or care taken to ensure that the buffers are not accessed while the
* channel remains open.
*
* @since 1.7
*/
public interface AsynchronousChannel
extends Channel
{
/**
* Closes this channel.
*
* <p> Any outstanding asynchronous operations upon this channel will
* complete with the exception {@link AsynchronousCloseException}. After a
* channel is closed then further attempts to initiate asynchronous I/O
* operations complete immediately with cause {@link ClosedChannelException}.
*
* <p> This method otherwise behaves exactly as specified by the {@link
* Channel} interface.
*
* @throws IOException
* If an I/O error occurs
*/
@Override
void close() throws IOException;
}

344
jdk/src/share/classes/java/nio/channels/AsynchronousChannelGroup.java Normal file
View file

@ -0,0 +1,344 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.channels;
import java.nio.channels.spi.AsynchronousChannelProvider;
import java.io.IOException;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.ThreadFactory;
import java.util.concurrent.TimeUnit;
/**
* A grouping of asynchronous channels for the purpose of resource sharing.
*
* <p> An asynchronous channel group encapsulates the mechanics required to
* handle the completion of I/O operations initiated by {@link AsynchronousChannel
* asynchronous channels} that are bound to the group. A group has an associated
* thread pool to which tasks are submitted to handle I/O events and dispatch to
* {@link CompletionHandler completion-handlers} that consume the result of
* asynchronous operations performed on channels in the group. In addition to
* handling I/O events, the pooled threads may also execute other tasks required
* to support the execution of asynchronous I/O operations.
*
* <p> An asynchronous channel group is created by invoking the {@link
* #withFixedThreadPool withFixedThreadPool} or {@link #withCachedThreadPool
* withCachedThreadPool} methods defined here. Channels are bound to a group by
* specifying the group when constructing the channel. The associated thread
* pool is <em>owned</em> by the group; termination of the group results in the
* shutdown of the associated thread pool.
*
* <p> In addition to groups created explicitly, the Java virtual machine
* maintains a system-wide <em>default group</em> that is constructed
* automatically. Asynchronous channels that do not specify a group at
* construction time are bound to the default group. The default group has an
* associated thread pool that creates new threads as needed. The default group
* may be configured by means of system properties defined in the table below.
* Where the {@link java.util.concurrent.ThreadFactory ThreadFactory} for the
* default group is not configured then the pooled threads of the default group
* are {@link Thread#isDaemon daemon} threads.
*
* <table border>
* <tr>
* <th>System property</th>
* <th>Description</th>
* </tr>
* <tr>
* <tr>
* <td> {@code java.nio.channels.DefaultThreadPool.threadFactory} </td>
* <td> The value of this property is taken to be the fully-qualified name
* of a concrete {@link java.util.concurrent.ThreadFactory ThreadFactory}
* class. The class is loaded using the system class loader and instantiated.
* The factory's {@link java.util.concurrent.ThreadFactory#newThread
* newThread} method is invoked to create each thread for the default
* group's thread pool. If the process to load and instantiate the value
* of the property fails then an unspecified error is thrown during the
* construction of the default group. </td>
* </tr>
* <tr>
* <td> {@code java.nio.channels.DefaultThreadPool.initialSize} </td>
* <td> The value of the {@code initialSize} parameter for the default
* group (see {@link #withCachedThreadPool withCachedThreadPool}).
* The value of the property is taken to be the {@code String}
* representation of an {@code Integer} that is the initial size parameter.
* If the value cannot be parsed as an {@code Integer} it causes an
* unspecified error to be thrown during the construction of the default
* group. </td>
* </tr>
* </table>
*
* <a name="threading"><h4>Threading</h4></a>
*
* <p> The completion handler for an I/O operation initiated on a channel bound
* to a group is guaranteed to be invoked by one of the pooled threads in the
* group. This ensures that the completion handler is run by a thread with the
* expected <em>identity</em>.
*
* <p> Where an I/O operation completes immediately, and the initiating thread
* is one of the pooled threads in the group then the completion handler may
* be invoked directly by the initiating thread. To avoid stack overflow, an
* implementation may impose a limit as to the number of activations on the
* thread stack. Some I/O operations may prohibit invoking the completion
* handler directly by the initiating thread (see {@link
* AsynchronousServerSocketChannel#accept(Object,CompletionHandler) accept}).
*
* <a name="shutdown"><h4>Shutdown and Termination</h4></a>
*
* <p> The {@link #shutdown() shutdown} method is used to initiate an <em>orderly
* shutdown</em> of a group. An orderly shutdown marks the group as shutdown;
* further attempts to construct a channel that binds to the group will throw
* {@link ShutdownChannelGroupException}. Whether or not a group is shutdown can
* be tested using the {@link #isShutdown() isShutdown} method. Once shutdown,
* the group <em>terminates</em> when all asynchronous channels that are bound to
* the group are closed, all actively executing completion handlers have run to
* completion, and resources used by the group are released. No attempt is made
* to stop or interrupt threads that are executing completion handlers. The
* {@link #isTerminated() isTerminated} method is used to test if the group has
* terminated, and the {@link #awaitTermination awaitTermination} method can be
* used to block until the group has terminated.
*
* <p> The {@link #shutdownNow() shutdownNow} method can be used to initiate a
* <em>forceful shutdown</em> of the group. In addition to the actions performed
* by an orderly shutdown, the {@code shutdownNow} method closes all open channels
* in the group as if by invoking the {@link AsynchronousChannel#close close}
* method.
*
* @since 1.7
*
* @see AsynchronousSocketChannel#open(AsynchronousChannelGroup)
* @see AsynchronousServerSocketChannel#open(AsynchronousChannelGroup)
*/
public abstract class AsynchronousChannelGroup {
private final AsynchronousChannelProvider provider;
/**
* Initialize a new instance of this class.
*
* @param provider
* The asynchronous channel provider for this group
*/
protected AsynchronousChannelGroup(AsynchronousChannelProvider provider) {
this.provider = provider;
}
/**
* Returns the provider that created this channel group.
*
* @return The provider that created this channel group
*/
public final AsynchronousChannelProvider provider() {
return provider;
}
/**
* Creates an asynchronous channel group with a fixed thread pool.
*
* <p> The resulting asynchronous channel group reuses a fixed number of
* threads. At any point, at most {@code nThreads} threads will be active
* processing tasks that are submitted to handle I/O events and dispatch
* completion results for operations initiated on asynchronous channels in
* the group.
*
* <p> The group is created by invoking the {@link
* AsynchronousChannelProvider#openAsynchronousChannelGroup(int,ThreadFactory)
* openAsynchronousChannelGroup(int,ThreadFactory)} method of the system-wide
* default {@link AsynchronousChannelProvider} object.
*
* @param nThreads
* The number of threads in the pool
* @param threadFactory
* The factory to use when creating new threads
*
* @return A new asynchronous channel group
*
* @throws IllegalArgumentException
* If {@code nThreads <= 0}
* @throws IOException
* If an I/O error occurs
*/
public static AsynchronousChannelGroup withFixedThreadPool(int nThreads,
ThreadFactory threadFactory)
throws IOException
{
return AsynchronousChannelProvider.provider()
.openAsynchronousChannelGroup(nThreads, threadFactory);
}
/**
* Creates an asynchronous channel group with a given thread pool that
* creates new threads as needed.
*
* <p> The {@code executor} parameter is an {@code ExecutorService} that
* creates new threads as needed to execute tasks that are submitted to
* handle I/O events and dispatch completion results for operations initiated
* on asynchronous channels in the group. It may reuse previously constructed
* threads when they are available.
*
* <p> The {@code initialSize} parameter may be used by the implementation
* as a <em>hint</em> as to the initial number of tasks it may submit. For
* example, it may be used to indictae the initial number of threads that
* wait on I/O events.
*
* <p> The executor is intended to be used exclusively by the resulting
* asynchronous channel group. Termination of the group results in the
* orderly {@link ExecutorService#shutdown shutdown} of the executor
* service. Shutting down the executor service by other means results in
* unspecified behavior.
*
* <p> The group is created by invoking the {@link
* AsynchronousChannelProvider#openAsynchronousChannelGroup(ExecutorService,int)
* openAsynchronousChannelGroup(ExecutorService,int)} method of the system-wide
* default {@link AsynchronousChannelProvider} object.
*
* @param executor
* The thread pool for the resulting group
* @param initialSize
* A value {@code >=0} or a negative value for implementation
* specific default
*
* @return A new asynchronous channel group
*
* @throws IOException
* If an I/O error occurs
*
* @see java.util.concurrent.Executors#newCachedThreadPool
*/
public static AsynchronousChannelGroup withCachedThreadPool(ExecutorService executor,
int initialSize)
throws IOException
{
return AsynchronousChannelProvider.provider()
.openAsynchronousChannelGroup(executor, initialSize);
}
/**
* Creates an asynchronous channel group with a given thread pool.
*
* <p> The {@code executor} parameter is an {@code ExecutorService} that
* executes tasks submitted to dispatch completion results for operations
* initiated on asynchronous channels in the group.
*
* <p> Care should be taken when configuring the executor service. It
* should support <em>direct handoff</em> or <em>unbounded queuing</em> of
* submitted tasks, and the thread that invokes the {@link
* ExecutorService#execute execute} method should never invoke the task
* directly. An implementation may mandate additional constraints.
*
* <p> The executor is intended to be used exclusively by the resulting
* asynchronous channel group. Termination of the group results in the
* orderly {@link ExecutorService#shutdown shutdown} of the executor
* service. Shutting down the executor service by other means results in
* unspecified behavior.
*
* <p> The group is created by invoking the {@link
* AsynchronousChannelProvider#openAsynchronousChannelGroup(ExecutorService,int)
* openAsynchronousChannelGroup(ExecutorService,int)} method of the system-wide
* default {@link AsynchronousChannelProvider} object with an {@code
* initialSize} of {@code 0}.
*
* @param executor
* The thread pool for the resulting group
*
* @return A new asynchronous channel group
*
* @throws IOException
* If an I/O error occurs
*/
public static AsynchronousChannelGroup withThreadPool(ExecutorService executor)
throws IOException
{
return AsynchronousChannelProvider.provider()
.openAsynchronousChannelGroup(executor, 0);
}
/**
* Tells whether or not this asynchronous channel group is shutdown.
*
* @return {@code true} if this asynchronous channel group is shutdown or
* has been marked for shutdown.
*/
public abstract boolean isShutdown();
/**
* Tells whether or not this group has terminated.
*
* <p> Where this method returns {@code true}, then the associated thread
* pool has also {@link ExecutorService#isTerminated terminated}.
*
* @return {@code true} if this group has terminated
*/
public abstract boolean isTerminated();
/**
* Initiates an orderly shutdown of the group.
*
* <p> This method marks the group as shutdown. Further attempts to construct
* channel that binds to this group will throw {@link ShutdownChannelGroupException}.
* The group terminates when all asynchronous channels in the group are
* closed, all actively executing completion handlers have run to completion,
* and all resources have been released. This method has no effect if the
* group is already shutdown.
*/
public abstract void shutdown();
/**
* Shuts down the group and closes all open channels in the group.
*
* <p> In addition to the actions performed by the {@link #shutdown() shutdown}
* method, this method invokes the {@link AsynchronousChannel#close close}
* method on all open channels in the group. This method does not attempt to
* stop or interrupt threads that are executing completion handlers. The
* group terminates when all actively executing completion handlers have run
* to completion and all resources have been released. This method may be
* invoked at any time. If some other thread has already invoked it, then
* another invocation will block until the first invocation is complete,
* after which it will return without effect.
*
* @throws IOException
* If an I/O error occurs
*/
public abstract void shutdownNow() throws IOException;
/**
* Awaits termination of the group.
* <p> This method blocks until the group has terminated, or the timeout
* occurs, or the current thread is interrupted, whichever happens first.
*
* @param timeout
* The maximum time to wait, or zero or less to not wait
* @param unit
* The time unit of the timeout argument
*
* @return {@code true} if the group has terminated; {@code false} if the
* timeout elapsed before termination
*
* @throws InterruptedException
* If interrupted while waiting
*/
public abstract boolean awaitTermination(long timeout, TimeUnit unit)
throws InterruptedException;
}

718
jdk/src/share/classes/java/nio/channels/AsynchronousDatagramChannel.java Normal file
View file

@ -0,0 +1,718 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.channels;
import java.nio.channels.spi.*;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.Future;
import java.io.IOException;
import java.net.SocketOption;
import java.net.SocketAddress;
import java.net.ProtocolFamily;
import java.nio.ByteBuffer;
/**
* An asynchronous channel for datagram-oriented sockets.
*
* <p> An asynchronous datagram channel is created by invoking one of the {@link
* #open open} methods defined by this class. It is not possible to create a channel
* for an arbitrary, pre-existing datagram socket. A newly-created asynchronous
* datagram channel is open but not connected. It need not be connected in order
* for the {@link #send send} and {@link #receive receive} methods to be used.
* A datagram channel may be connected, by invoking its {@link #connect connect}
* method, in order to avoid the overhead of the security checks that are otherwise
* performed as part of every send and receive operation when a security manager
* is set. The channel must be connected in order to use the {@link #read read}
* and {@link #write write} methods, since those methods do not accept or return
* socket addresses. Once connected, an asynchronous datagram channel remains
* connected until it is disconnected or closed.
*
* <p> Socket options are configured using the {@link #setOption(SocketOption,Object)
* setOption} method. An asynchronous datagram channel to an Internet Protocol
* (IP) socket supports the following options:
* <blockquote>
* <table border>
* <tr>
* <th>Option Name</th>
* <th>Description</th>
* </tr>
* <tr>
* <td> {@link java.net.StandardSocketOption#SO_SNDBUF SO_SNDBUF} </td>
* <td> The size of the socket send buffer </td>
* </tr>
* <tr>
* <td> {@link java.net.StandardSocketOption#SO_RCVBUF SO_RCVBUF} </td>
* <td> The size of the socket receive buffer </td>
* </tr>
* <tr>
* <td> {@link java.net.StandardSocketOption#SO_REUSEADDR SO_REUSEADDR} </td>
* <td> Re-use address </td>
* </tr>
* <tr>
* <td> {@link java.net.StandardSocketOption#SO_BROADCAST SO_BROADCAST} </td>
* <td> Allow transmission of broadcast datagrams </td>
* </tr>
* <tr>
* <td> {@link java.net.StandardSocketOption#IP_TOS IP_TOS} </td>
* <td> The Type of Service (ToS) octet in the Internet Protocol (IP) header </td>
* </tr>
* <tr>
* <td> {@link java.net.StandardSocketOption#IP_MULTICAST_IF IP_MULTICAST_IF} </td>
* <td> The network interface for Internet Protocol (IP) multicast datagrams </td>
* </tr>
* <tr>
* <td> {@link java.net.StandardSocketOption#IP_MULTICAST_TTL
* IP_MULTICAST_TTL} </td>
* <td> The <em>time-to-live</em> for Internet Protocol (IP) multicast
* datagrams </td>
* </tr>
* <tr>
* <td> {@link java.net.StandardSocketOption#IP_MULTICAST_LOOP
* IP_MULTICAST_LOOP} </td>
* <td> Loopback for Internet Protocol (IP) multicast datagrams </td>
* </tr>
* </table>
* </blockquote>
* Additional (implementation specific) options may also be supported.
*
* <p> Asynchronous datagram channels allow more than one read/receive and
* write/send to be oustanding at any given time.
*
* <p> <b>Usage Example:</b>
* <pre>
* final AsynchronousDatagramChannel dc = AsynchronousDatagramChannel.open()
* .bind(new InetSocketAddress(4000));
*
* // print the source address of all packets that we receive
* dc.receive(buffer, buffer, new CompletionHandler&lt;SocketAddress,ByteBuffer&gt;() {
* public void completed(SocketAddress sa, ByteBuffer buffer) {
* try {
* System.out.println(sa);
*
* buffer.clear();
* dc.receive(buffer, buffer, this);
* } catch (...) { ... }
* }
* public void failed(Throwable exc, ByteBuffer buffer) {
* ...
* }
* public void cancelled(ByteBuffer buffer) {
* ...
* }
* });
* </pre>
*
* @since 1.7
*/
public abstract class AsynchronousDatagramChannel
implements AsynchronousByteChannel, MulticastChannel
{
private final AsynchronousChannelProvider provider;
/**
* Initializes a new instance of this class.
*/
protected AsynchronousDatagramChannel(AsynchronousChannelProvider provider) {
this.provider = provider;
}
/**
* Returns the provider that created this channel.
*/
public final AsynchronousChannelProvider provider() {
return provider;
}
/**
* Opens an asynchronous datagram channel.
*
* <p> The new channel is created by invoking the {@link
* java.nio.channels.spi.AsynchronousChannelProvider#openAsynchronousDatagramChannel
* openAsynchronousDatagramChannel} method on the {@link
* java.nio.channels.spi.AsynchronousChannelProvider} object that created
* the given group (or the default provider where {@code group} is {@code
* null}).
*
* <p> The {@code family} parameter is used to specify the {@link ProtocolFamily}.
* If the datagram channel is to be used for Internet Protocol {@link
* MulticastChannel multicasting} then this parameter should correspond to
* the address type of the multicast groups that this channel will join.
*
* @param family
* The protocol family, or {@code null} to use the default protocol
* family
* @param group
* The group to which the newly constructed channel should be bound,
* or {@code null} for the default group
*
* @return A new asynchronous datagram channel
*
* @throws UnsupportedOperationException
* If the specified protocol family is not supported. For example,
* suppose the parameter is specified as {@link
* java.net.StandardProtocolFamily#INET6 INET6} but IPv6 is not
* enabled on the platform.
* @throws ShutdownChannelGroupException
* The specified group is shutdown
* @throws IOException
* If an I/O error occurs
*/
public static AsynchronousDatagramChannel open(ProtocolFamily family,
AsynchronousChannelGroup group)
throws IOException
{
AsynchronousChannelProvider provider = (group == null) ?
AsynchronousChannelProvider.provider() : group.provider();
return provider.openAsynchronousDatagramChannel(family, group);
}
/**
* Opens an asynchronous datagram channel.
*
* <p> This method returns an asynchronous datagram channel that is
* bound to the <em>default group</em>. This method is equivalent to evaluating
* the expression:
* <blockquote><pre>
* open((ProtocolFamily)null,&nbsp;(AsynchronousChannelGroup)null);
* </pre></blockquote>
*
* @return A new asynchronous datagram channel
*
* @throws IOException
* If an I/O error occurs
*/
public static AsynchronousDatagramChannel open()
throws IOException
{
return open(null, null);
}
// -- Socket-specific operations --
/**
* @throws AlreadyBoundException {@inheritDoc}
* @throws UnsupportedAddressTypeException {@inheritDoc}
* @throws ClosedChannelException {@inheritDoc}
* @throws IOException {@inheritDoc}
* @throws SecurityException
* If a security manager has been installed and its {@link
* SecurityManager#checkListen checkListen} method denies the
* operation
*/
@Override
public abstract AsynchronousDatagramChannel bind(SocketAddress local)
throws IOException;
/**
* @throws IllegalArgumentException {@inheritDoc}
* @throws ClosedChannelException {@inheritDoc}
* @throws IOException {@inheritDoc}
*/
@Override
public abstract <T> AsynchronousDatagramChannel setOption(SocketOption<T> name, T value)
throws IOException;
/**
* Returns the remote address to which this channel is connected.
*
* <p> Where the channel is connected to an Internet Protocol socket address
* then the return value from this method is of type {@link
* java.net.InetSocketAddress}.
*
* @return The remote address; {@code null} if the channel's socket is not
* connected
*
* @throws ClosedChannelException
* If the channel is closed
* @throws IOException
* If an I/O error occurs
*/
public abstract SocketAddress getRemoteAddress() throws IOException;
/**
* Connects this channel's socket.
*
* <p> The channel's socket is configured so that it only receives
* datagrams from, and sends datagrams to, the given remote <i>peer</i>
* address. Once connected, datagrams may not be received from or sent to
* any other address. A datagram socket remains connected until it is
* explicitly disconnected or until it is closed.
*
* <p> This method performs exactly the same security checks as the {@link
* java.net.DatagramSocket#connect connect} method of the {@link
* java.net.DatagramSocket} class. That is, if a security manager has been
* installed then this method verifies that its {@link
* java.lang.SecurityManager#checkAccept checkAccept} and {@link
* java.lang.SecurityManager#checkConnect checkConnect} methods permit
* datagrams to be received from and sent to, respectively, the given
* remote address.
*
* <p> This method may be invoked at any time. Whether it has any effect
* on outstanding read or write operations is implementation specific and
* therefore not specified.
*
* @param remote
* The remote address to which this channel is to be connected
*
* @return This datagram channel
*
* @throws ClosedChannelException
* If this channel is closed
*
* @throws SecurityException
* If a security manager has been installed
* and it does not permit access to the given remote address
*
* @throws IOException
* If some other I/O error occurs
*/
public abstract AsynchronousDatagramChannel connect(SocketAddress remote)
throws IOException;
/**
* Disconnects this channel's socket.
*
* <p> The channel's socket is configured so that it can receive datagrams
* from, and sends datagrams to, any remote address so long as the security
* manager, if installed, permits it.
*
* <p> This method may be invoked at any time. Whether it has any effect
* on outstanding read or write operations is implementation specific and
* therefore not specified.
*
* @return This datagram channel
*
* @throws IOException
* If some other I/O error occurs
*/
public abstract AsynchronousDatagramChannel disconnect() throws IOException;
/**
* Receives a datagram via this channel.
*
* <p> This method initiates the receiving of a datagram, returning a
* {@code Future} representing the pending result of the operation.
* The {@code Future}'s {@link Future#get() get} method returns
* the source address of the datagram upon successful completion.
*
* <p> The datagram is transferred into the given byte buffer starting at
* its current position, as if by a regular {@link AsynchronousByteChannel#read
* read} operation. If there are fewer bytes remaining in the buffer
* than are required to hold the datagram then the remainder of the datagram
* is silently discarded.
*
* <p> If a timeout is specified and the timeout elapses before the operation
* completes then the operation completes with the exception {@link
* InterruptedByTimeoutException}. When a timeout elapses then the state of
* the {@link ByteBuffer} is not defined. The buffers should be discarded or
* at least care must be taken to ensure that the buffer is not accessed
* while the channel remains open.
*
* <p> When a security manager has been installed and the channel is not
* connected, then it verifies that the source's address and port number are
* permitted by the security manager's {@link SecurityManager#checkAccept
* checkAccept} method. The permission check is performed with privileges that
* are restricted by the calling context of this method. If the permission
* check fails then the operation completes with a {@link SecurityException}.
* The overhead of this security check can be avoided by first connecting the
* socket via the {@link #connect connect} method.
*
* @param dst
* The buffer into which the datagram is to be transferred
* @param timeout
* The timeout, or {@code 0L} for no timeout
* @param unit
* The time unit of the {@code timeout} argument
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
* The handler for consuming the result; can be {@code null}
*
* @return a {@code Future} object representing the pending result
*
* @throws IllegalArgumentException
* If the timeout is negative or the buffer is read-only
* @throws ShutdownChannelGroupException
* If a handler is specified, and the channel group is shutdown
*/
public abstract <A> Future<SocketAddress> receive(ByteBuffer dst,
long timeout,
TimeUnit unit,
A attachment,
CompletionHandler<SocketAddress,? super A> handler);
/**
* Receives a datagram via this channel.
*
* <p> This method initiates the receiving of a datagram, returning a
* {@code Future} representing the pending result of the operation.
* The {@code Future}'s {@link Future#get() get} method returns
* the source address of the datagram upon successful completion.
*
* <p> This method is equivalent to invoking {@link
* #receive(ByteBuffer,long,TimeUnit,Object,CompletionHandler)} with a
* timeout of {@code 0L}.
*
* @param dst
* The buffer into which the datagram is to be transferred
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
* The handler for consuming the result; can be {@code null}
*
* @return a {@code Future} object representing the pending result
*
* @throws IllegalArgumentException
* If the buffer is read-only
* @throws ShutdownChannelGroupException
* If a handler is specified, and the channel group is shutdown
*/
public final <A> Future<SocketAddress> receive(ByteBuffer dst,
A attachment,
CompletionHandler<SocketAddress,? super A> handler)
{
return receive(dst, 0L, TimeUnit.MILLISECONDS, attachment, handler);
}
/**
* Receives a datagram via this channel.
*
* <p> This method initiates the receiving of a datagram, returning a
* {@code Future} representing the pending result of the operation.
* The {@code Future}'s {@link Future#get() get} method returns
* the source address of the datagram upon successful completion.
*
* <p> This method is equivalent to invoking {@link
* #receive(ByteBuffer,long,TimeUnit,Object,CompletionHandler)} with a
* timeout of {@code 0L}, and an attachment and completion handler
* of {@code null}.
*
* @param dst
* The buffer into which the datagram is to be transferred
*
* @return a {@code Future} object representing the pending result
*
* @throws IllegalArgumentException
* If the buffer is read-only
*/
public final <A> Future<SocketAddress> receive(ByteBuffer dst) {
return receive(dst, 0L, TimeUnit.MILLISECONDS, null, null);
}
/**
* Sends a datagram via this channel.
*
* <p> This method initiates sending of a datagram, returning a
* {@code Future} representing the pending result of the operation.
* The operation sends the remaining bytes in the given buffer as a single
* datagram to the given target address. The result of the operation, obtained
* by invoking the {@code Future}'s {@link Future#get() get}
* method, is the number of bytes sent.
*
* <p> The datagram is transferred from the byte buffer as if by a regular
* {@link AsynchronousByteChannel#write write} operation.
*
* <p> If a timeout is specified and the timeout elapses before the operation
* completes then the operation completes with the exception {@link
* InterruptedByTimeoutException}. When a timeout elapses then the state of
* the {@link ByteBuffer} is not defined. The buffers should be discarded or
* at least care must be taken to ensure that the buffer is not accessed
* while the channel remains open.
*
* <p> If there is a security manager installed and the the channel is not
* connected then this method verifies that the target address and port number
* are permitted by the security manager's {@link SecurityManager#checkConnect
* checkConnect} method. The overhead of this security check can be avoided
* by first connecting the socket via the {@link #connect connect} method.
*
* @param src
* The buffer containing the datagram to be sent
* @param target
* The address to which the datagram is to be sent
* @param timeout
* The timeout, or {@code 0L} for no timeout
* @param unit
* The time unit of the {@code timeout} argument
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
* The handler for consuming the result; can be {@code null}
*
* @return a {@code Future} object representing the pending result
*
* @throws UnresolvedAddressException
* If the given remote address is not fully resolved
* @throws UnsupportedAddressTypeException
* If the type of the given remote address is not supported
* @throws IllegalArgumentException
* If the timeout is negative, or if the channel's socket is
* connected to an address that is not equal to {@code target}
* @throws SecurityException
* If a security manager has been installed and it does not permit
* datagrams to be sent to the given address
* @throws ShutdownChannelGroupException
* If a handler is specified, and the channel group is shutdown
*/
public abstract <A> Future<Integer> send(ByteBuffer src,
SocketAddress target,
long timeout,
TimeUnit unit,
A attachment,
CompletionHandler<Integer,? super A> handler);
/**
* Sends a datagram via this channel.
*
* <p> This method initiates sending of a datagram, returning a
* {@code Future} representing the pending result of the operation.
* The operation sends the remaining bytes in the given buffer as a single
* datagram to the given target address. The result of the operation, obtained
* by invoking the {@code Future}'s {@link Future#get() get}
* method, is the number of bytes sent.
*
* <p> This method is equivalent to invoking {@link
* #send(ByteBuffer,SocketAddress,long,TimeUnit,Object,CompletionHandler)}
* with a timeout of {@code 0L}.
*
* @param src
* The buffer containing the datagram to be sent
* @param target
* The address to which the datagram is to be sent
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
* The handler for consuming the result; can be {@code null}
*
* @return a {@code Future} object representing the pending result
*
* @throws UnresolvedAddressException
* If the given remote address is not fully resolved
* @throws UnsupportedAddressTypeException
* If the type of the given remote address is not supported
* @throws IllegalArgumentException
* If the channel's socket is connected and is connected to an
* address that is not equal to {@code target}
* @throws SecurityException
* If a security manager has been installed and it does not permit
* datagrams to be sent to the given address
* @throws ShutdownChannelGroupException
* If a handler is specified, and the channel group is shutdown
*/
public final <A> Future<Integer> send(ByteBuffer src,
SocketAddress target,
A attachment,
CompletionHandler<Integer,? super A> handler)
{
return send(src, target, 0L, TimeUnit.MILLISECONDS, attachment, handler);
}
/**
* Sends a datagram via this channel.
*
* <p> This method initiates sending of a datagram, returning a
* {@code Future} representing the pending result of the operation.
* The operation sends the remaining bytes in the given buffer as a single
* datagram to the given target address. The result of the operation, obtained
* by invoking the {@code Future}'s {@link Future#get() get}
* method, is the number of bytes sent.
*
* <p> This method is equivalent to invoking {@link
* #send(ByteBuffer,SocketAddress,long,TimeUnit,Object,CompletionHandler)}
* with a timeout of {@code 0L} and an attachment and completion handler
* of {@code null}.
*
* @param src
* The buffer containing the datagram to be sent
* @param target
* The address to which the datagram is to be sent
*
* @return a {@code Future} object representing the pending result
*
* @throws UnresolvedAddressException
* If the given remote address is not fully resolved
* @throws UnsupportedAddressTypeException
* If the type of the given remote address is not supported
* @throws IllegalArgumentException
* If the channel's socket is connected and is connected to an
* address that is not equal to {@code target}
* @throws SecurityException
* If a security manager has been installed and it does not permit
* datagrams to be sent to the given address
*/
public final Future<Integer> send(ByteBuffer src, SocketAddress target) {
return send(src, target, 0L, TimeUnit.MILLISECONDS, null, null);
}
/**
* Receives a datagram via this channel.
*
* <p> This method initiates the receiving of a datagram, returning a
* {@code Future} representing the pending result of the operation.
* The {@code Future}'s {@link Future#get() get} method returns
* the number of bytes transferred upon successful completion.
*
* <p> This method may only be invoked if this channel is connected, and it
* only accepts datagrams from the peer that the channel is connected too.
* The datagram is transferred into the given byte buffer starting at
* its current position and exactly as specified in the {@link
* AsynchronousByteChannel} interface. If there are fewer bytes
* remaining in the buffer than are required to hold the datagram then the
* remainder of the datagram is silently discarded.
*
* <p> If a timeout is specified and the timeout elapses before the operation
* completes then the operation completes with the exception {@link
* InterruptedByTimeoutException}. When a timeout elapses then the state of
* the {@link ByteBuffer} is not defined. The buffers should be discarded or
* at least care must be taken to ensure that the buffer is not accessed
* while the channel remains open.
*
* @param dst
* The buffer into which the datagram is to be transferred
* @param timeout
* The timeout, or {@code 0L} for no timeout
* @param unit
* The time unit of the {@code timeout} argument
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
* The handler for consuming the result; can be {@code null}
*
* @return a {@code Future} object representing the pending result
*
* @throws IllegalArgumentException
* If the timeout is negative or buffer is read-only
* @throws NotYetConnectedException
* If this channel is not connected
* @throws ShutdownChannelGroupException
* If a handler is specified, and the channel group is shutdown
*/
public abstract <A> Future<Integer> read(ByteBuffer dst,
long timeout,
TimeUnit unit,
A attachment,
CompletionHandler<Integer,? super A> handler);
/**
* @throws NotYetConnectedException
* If this channel is not connected
* @throws ShutdownChannelGroupException
* If a handler is specified, and the channel group is shutdown
*/
@Override
public final <A> Future<Integer> read(ByteBuffer dst,
A attachment,
CompletionHandler<Integer,? super A> handler)
{
return read(dst, 0L, TimeUnit.MILLISECONDS, attachment, handler);
}
/**
* @throws NotYetConnectedException
* If this channel is not connected
* @throws ShutdownChannelGroupException
* If a handler is specified, and the channel group is shutdown
*/
@Override
public final Future<Integer> read(ByteBuffer dst) {
return read(dst, 0L, TimeUnit.MILLISECONDS, null, null);
}
/**
* Writes a datagram to this channel.
*
* <p> This method initiates sending of a datagram, returning a
* {@code Future} representing the pending result of the operation.
* The operation sends the remaining bytes in the given buffer as a single
* datagram. The result of the operation, obtained by invoking the
* {@code Future}'s {@link Future#get() get} method, is the
* number of bytes sent.
*
* <p> The datagram is transferred from the byte buffer as if by a regular
* {@link AsynchronousByteChannel#write write} operation.
*
* <p> This method may only be invoked if this channel is connected,
* in which case it sends datagrams directly to the socket's peer. Otherwise
* it behaves exactly as specified in the {@link
* AsynchronousByteChannel} interface.
*
* <p> If a timeout is specified and the timeout elapses before the operation
* completes then the operation completes with the exception {@link
* InterruptedByTimeoutException}. When a timeout elapses then the state of
* the {@link ByteBuffer} is not defined. The buffers should be discarded or
* at least care must be taken to ensure that the buffer is not accessed
* while the channel remains open.
*
* @param src
* The buffer containing the datagram to be sent
* @param timeout
* The timeout, or {@code 0L} for no timeout
* @param unit
* The time unit of the {@code timeout} argument
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
* The handler for consuming the result; can be {@code null}
*
* @return a {@code Future} object representing the pending result
*
* @throws IllegalArgumentException
* If the timeout is negative
* @throws NotYetConnectedException
* If this channel is not connected
* @throws ShutdownChannelGroupException
* If a handler is specified, and the channel group is shutdown
*/
public abstract <A> Future<Integer> write(ByteBuffer src,
long timeout,
TimeUnit unit,
A attachment,
CompletionHandler<Integer,? super A> handler);
/**
* @throws NotYetConnectedException
* If this channel is not connected
* @throws ShutdownChannelGroupException
* If a handler is specified, and the channel group is shutdown
*/
@Override
public final <A> Future<Integer> write(ByteBuffer src,
A attachment,
CompletionHandler<Integer,? super A> handler)
{
return write(src, 0L, TimeUnit.MILLISECONDS, attachment, handler);
}
/**
* @throws NotYetConnectedException
* If this channel is not connected
* @throws ShutdownChannelGroupException
* If a handler is specified, and the channel group is shutdown
*/
@Override
public final Future<Integer> write(ByteBuffer src) {
return write(src, 0L, TimeUnit.MILLISECONDS, null, null);
}
}

774
jdk/src/share/classes/java/nio/channels/AsynchronousFileChannel.java Normal file
View file

@ -0,0 +1,774 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.channels;
import java.nio.file.*;
import java.nio.file.attribute.FileAttribute;
import java.nio.file.spi.*;
import java.nio.ByteBuffer;
import java.io.IOException;
import java.util.concurrent.Future;
import java.util.concurrent.ExecutorService;
import java.util.Set;
import java.util.HashSet;
import java.util.Collections;
/**
* An asynchronous channel for reading, writing, and manipulating a file.
*
* <p> An asynchronous file channel is created when a file is opened by invoking
* one of the {@link #open open} methods defined by this class. The file contains
* a variable-length sequence of bytes that can be read and written and whose
* current size can be {@link #size() queried}. The size of the file increases
* when bytes are written beyond its current size; the size of the file decreases
* when it is {@link #truncate truncated}.
*
* <p> An asynchronous file channel does not have a <i>current position</i>
* within the file. Instead, the file position is specified to each read and
* write operation.
*
* <p> In addition to read and write operations, this class defines the
* following operations: </p>
*
* <ul>
*
* <li><p> Updates made to a file may be {@link #force <i>forced
* out</i>} to the underlying storage device, ensuring that data are not
* lost in the event of a system crash. </p></li>
*
* <li><p> A region of a file may be {@link FileLock <i>locked</i>}
* against access by other programs. </p></li>
*
* </ul>
*
* <p> The {@link #read read}, {@link #write write}, and {@link #lock lock}
* methods defined by this class are asynchronous and return a {@link Future}
* to represent the pending result of the operation. This may be used to check
* if the operation has completed, to wait for its completion, and to retrieve
* the result. These method may optionally specify a {@link CompletionHandler}
* that is invoked to consume the result of the I/O operation when it completes.
*
* <p> An {@code AsynchronousFileChannel} is associated with a thread pool to
* which tasks are submitted to handle I/O events and dispatch to completion
* handlers that consume the results of I/O operations on the channel. The
* completion handler for an I/O operation initiated on a channel is guaranteed
* to be invoked by one threads in the thread pool (This ensures that the
* completion handler is run by a thread with the expected <em>identity</em>).
* Where an I/O operation completes immediately, and the initiating thread is
* itself a thread in the thread pool, then the completion handler may be invoked
* directly by the initiating thread. When an {@code AsynchronousFileChannel} is
* created without specifying a thread pool then the channel is associated with
* a system-dependent and default thread pool that may be shared with other
* channels. The default thread pool is configured by the system properties
* defined by the {@link AsynchronousChannelGroup} class.
*
* <p> Channels of this type are safe for use by multiple concurrent threads. The
* {@link Channel#close close} method may be invoked at any time, as specified
* by the {@link Channel} interface. This causes all outstanding asynchronous
* operations on the channel to complete with the exception {@link
* AsynchronousCloseException}. Multiple read and write operations may be
* outstanding at the same time. When multiple read and write operations are
* outstanding then the ordering of the I/O operations, and the order that the
* completion handlers are invoked, is not specified; they are not, in particular,
* guaranteed to execute in the order that the operations were initiated. The
* {@link java.nio.ByteBuffer ByteBuffers} used when reading or writing are not
* safe for use by multiple concurrent I/O operations. Furthermore, after an I/O
* operation is initiated then care should be taken to ensure that the buffer is
* not accessed until after the operation has completed.
*
* <p> As with {@link FileChannel}, the view of a file provided by an instance of
* this class is guaranteed to be consistent with other views of the same file
* provided by other instances in the same program. The view provided by an
* instance of this class may or may not, however, be consistent with the views
* seen by other concurrently-running programs due to caching performed by the
* underlying operating system and delays induced by network-filesystem protocols.
* This is true regardless of the language in which these other programs are
* written, and whether they are running on the same machine or on some other
* machine. The exact nature of any such inconsistencies are system-dependent
* and are therefore unspecified.
*
* @since 1.7
*/
public abstract class AsynchronousFileChannel
implements AsynchronousChannel
{
/**
* Initializes a new instance of this class.
*/
protected AsynchronousFileChannel() {
}
/**
* Closes this channel.
*
* <p> If this channel is associated with its own thread pool then closing
* the channel causes the thread pool to shutdown after all actively
* executing completion handlers have completed. No attempt is made to stop
* or interrupt actively completion handlers.
*
* <p> This method otherwise behaves exactly as specified by the {@link
* AsynchronousChannel} interface.
*
* @throws IOException {@inheritDoc}
*/
@Override
public abstract void close() throws IOException;
/**
* Opens or creates a file for reading and/or writing, returning an
* asynchronous file channel to access the file.
*
* <p> The {@code options} parameter determines how the file is opened.
* The {@link StandardOpenOption#READ READ} and {@link StandardOpenOption#WRITE
* WRITE} options determines if the file should be opened for reading and/or
* writing. If neither option is contained in the array then an existing file
* is opened for reading.
*
* <p> In addition to {@code READ} and {@code WRITE}, the following options
* may be present:
*
* <table border=1 cellpadding=5 summary="">
* <tr> <th>Option</th> <th>Description</th> </tr>
* <tr>
* <td> {@link StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING} </td>
* <td> When opening an existing file, the file is first truncated to a
* size of 0 bytes. This option is ignored when the file is opened only
* for reading.</td>
* </tr>
* <tr>
* <td> {@link StandardOpenOption#CREATE_NEW CREATE_NEW} </td>
* <td> If this option is present then a new file is created, failing if
* the file already exists. When creating a file the check for the
* existence of the file and the creation of the file if it does not exist
* is atomic with respect to other file system operations. This option is
* ignored when the file is opened only for reading. </td>
* </tr>
* <tr>
* <td > {@link StandardOpenOption#CREATE CREATE} </td>
* <td> If this option is present then an existing file is opened if it
* exists, otherwise a new file is created. When creating a file the check
* for the existence of the file and the creation of the file if it does
* not exist is atomic with respect to other file system operations. This
* option is ignored if the {@code CREATE_NEW} option is also present or
* the file is opened only for reading. </td>
* </tr>
* <tr>
* <td > {@link StandardOpenOption#DELETE_ON_CLOSE DELETE_ON_CLOSE} </td>
* <td> When this option is present then the implementation makes a
* <em>best effort</em> attempt to delete the file when closed by the
* the {@link #close close} method. If the {@code close} method is not
* invoked then a <em>best effort</em> attempt is made to delete the file
* when the Java virtual machine terminates. </td>
* </tr>
* <tr>
* <td>{@link StandardOpenOption#SPARSE SPARSE} </td>
* <td> When creating a new file this option is a <em>hint</em> that the
* new file will be sparse. This option is ignored when not creating
* a new file. </td>
* </tr>
* <tr>
* <td> {@link StandardOpenOption#SYNC SYNC} </td>
* <td> Requires that every update to the file's content or metadata be
* written synchronously to the underlying storage device. (see <a
* href="../file/package-summary.html#integrity"> Synchronized I/O file
* integrity</a>). </td>
* <tr>
* <tr>
* <td> {@link StandardOpenOption#DSYNC DSYNC} </td>
* <td> Requires that every update to the file's content be written
* synchronously to the underlying storage device. (see <a
* href="../file/package-summary.html#integrity"> Synchronized I/O file
* integrity</a>). </td>
* </tr>
* </table>
*
* <p> An implementation may also support additional options.
*
* <p> The {@code executor} parameter is the {@link ExecutorService} to
* which tasks are submitted to handle I/O events and dispatch completion
* results for operations initiated on resulting channel.
* The nature of these tasks is highly implementation specific and so care
* should be taken when configuring the {@code Executor}. Minimally it
* should support an unbounded work queue and should not run tasks on the
* caller thread of the {@link ExecutorService#execute execute} method.
* {@link #close Closing} the channel results in the orderly {@link
* ExecutorService#shutdown shutdown} of the executor service. Shutting down
* the executor service by other means results in unspecified behavior.
*
* <p> The {@code attrs} parameter is an optional array of file {@link
* FileAttribute file-attributes} to set atomically when creating the file.
*
* <p> The new channel is created by invoking the {@link
* FileSystemProvider#newFileChannel newFileChannel} method on the
* provider that created the {@code Path}.
*
* @param file
* The path of the file to open or create
* @param options
* Options specifying how the file is opened
* @param executor
* The thread pool or {@code null} to associate the channel with
* the default thread pool
* @param attrs
* An optional list of file attributes to set atomically when
* creating the file
*
* @return A new asynchronous file channel
*
* @throws IllegalArgumentException
* If the set contains an invalid combination of options
* @throws UnsupportedOperationException
* If the {@code file} is associated with a provider that does not
* support creating asynchronous file channels, or an unsupported
* open option is specified, or the array contains an attribute that
* cannot be set atomically when creating the file
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* If a security manager is installed and it denies an
* unspecified permission required by the implementation.
* In the case of the default provider, the {@link
* SecurityManager#checkRead(String)} method is invoked to check
* read access if the file is opened for reading. The {@link
* SecurityManager#checkWrite(String)} method is invoked to check
* write access if the file is opened for writing
*/
public static AsynchronousFileChannel open(Path file,
Set<? extends OpenOption> options,
ExecutorService executor,
FileAttribute<?>... attrs)
throws IOException
{
FileSystemProvider provider = file.getFileSystem().provider();
return provider.newAsynchronousFileChannel(file, options, executor, attrs);
}
private static final FileAttribute<?>[] NO_ATTRIBUTES = new FileAttribute[0];
/**
* Opens or creates a file for reading and/or writing, returning an
* asynchronous file channel to access the file.
*
* <p> An invocation of this method behaves in exactly the same way as the
* invocation
* <pre>
* ch.{@link #open(Path,Set,ExecutorService,FileAttribute[]) open}(file, opts, null, new FileAttribute&lt;?&gt;[0]);
* </pre>
* where {@code opts} is a {@code Set} containing the options specified to
* this method.
*
* <p> The resulting channel is associated with default thread pool to which
* tasks are submitted to handle I/O events and dispatch to completion
* handlers that consume the result of asynchronous operations performed on
* the resulting channel.
*
* @param file
* The path of the file to open or create
* @param options
* Options specifying how the file is opened
*
* @return A new asynchronous file channel
*
* @throws IllegalArgumentException
* If the set contains an invalid combination of options
* @throws UnsupportedOperationException
* If the {@code file} is associated with a provider that does not
* support creating file channels, or an unsupported open option is
* specified
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* If a security manager is installed and it denies an
* unspecified permission required by the implementation.
* In the case of the default provider, the {@link
* SecurityManager#checkRead(String)} method is invoked to check
* read access if the file is opened for reading. The {@link
* SecurityManager#checkWrite(String)} method is invoked to check
* write access if the file is opened for writing
*/
public static AsynchronousFileChannel open(Path file, OpenOption... options)
throws IOException
{
Set<OpenOption> set = new HashSet<OpenOption>(options.length);
Collections.addAll(set, options);
return open(file, set, null, NO_ATTRIBUTES);
}
/**
* Returns the current size of this channel's file.
*
* @return The current size of this channel's file, measured in bytes
*
* @throws ClosedChannelException
* If this channel is closed
* @throws IOException
* If some other I/O error occurs
*/
public abstract long size() throws IOException;
/**
* Truncates this channel's file to the given size.
*
* <p> If the given size is less than the file's current size then the file
* is truncated, discarding any bytes beyond the new end of the file. If
* the given size is greater than or equal to the file's current size then
* the file is not modified. </p>
*
* @param size
* The new size, a non-negative byte count
*
* @return This file channel
*
* @throws NonWritableChannelException
* If this channel was not opened for writing
*
* @throws ClosedChannelException
* If this channel is closed
*
* @throws IllegalArgumentException
* If the new size is negative
*
* @throws IOException
* If some other I/O error occurs
*/
public abstract AsynchronousFileChannel truncate(long size) throws IOException;
/**
* Forces any updates to this channel's file to be written to the storage
* device that contains it.
*
* <p> If this channel's file resides on a local storage device then when
* this method returns it is guaranteed that all changes made to the file
* since this channel was created, or since this method was last invoked,
* will have been written to that device. This is useful for ensuring that
* critical information is not lost in the event of a system crash.
*
* <p> If the file does not reside on a local device then no such guarantee
* is made.
*
* <p> The {@code metaData} parameter can be used to limit the number of
* I/O operations that this method is required to perform. Passing
* {@code false} for this parameter indicates that only updates to the
* file's content need be written to storage; passing {@code true}
* indicates that updates to both the file's content and metadata must be
* written, which generally requires at least one more I/O operation.
* Whether this parameter actually has any effect is dependent upon the
* underlying operating system and is therefore unspecified.
*
* <p> Invoking this method may cause an I/O operation to occur even if the
* channel was only opened for reading. Some operating systems, for
* example, maintain a last-access time as part of a file's metadata, and
* this time is updated whenever the file is read. Whether or not this is
* actually done is system-dependent and is therefore unspecified.
*
* <p> This method is only guaranteed to force changes that were made to
* this channel's file via the methods defined in this class.
*
* @param metaData
* If {@code true} then this method is required to force changes
* to both the file's content and metadata to be written to
* storage; otherwise, it need only force content changes to be
* written
*
* @throws ClosedChannelException
* If this channel is closed
*
* @throws IOException
* If some other I/O error occurs
*/
public abstract void force(boolean metaData) throws IOException;
/**
* Acquires a lock on the given region of this channel's file.
*
* <p> This method initiates an operation to acquire a lock on the given region
* of this channel's file. The method returns a {@code Future} representing
* the pending result of the operation. Its {@link Future#get() get}
* method returns the {@link FileLock} on successful completion.
*
* <p> The region specified by the {@code position} and {@code size}
* parameters need not be contained within, or even overlap, the actual
* underlying file. Lock regions are fixed in size; if a locked region
* initially contains the end of the file and the file grows beyond the
* region then the new portion of the file will not be covered by the lock.
* If a file is expected to grow in size and a lock on the entire file is
* required then a region starting at zero, and no smaller than the
* expected maximum size of the file, should be locked. The two-argument
* {@link #lock(Object,CompletionHandler)} method simply locks a region
* of size {@link Long#MAX_VALUE}. If a lock that overlaps the requested
* region is already held by this Java virtual machine, or this method has
* been invoked to lock an overlapping region and that operation has not
* completed, then this method throws {@link OverlappingFileLockException}.
*
* <p> Some operating systems do not support a mechanism to acquire a file
* lock in an asynchronous manner. Consequently an implementation may
* acquire the file lock in a background thread or from a task executed by
* a thread in the associated thread pool. If there are many lock operations
* outstanding then it may consume threads in the Java virtual machine for
* indefinite periods.
*
* <p> Some operating systems do not support shared locks, in which case a
* request for a shared lock is automatically converted into a request for
* an exclusive lock. Whether the newly-acquired lock is shared or
* exclusive may be tested by invoking the resulting lock object's {@link
* FileLock#isShared() isShared} method.
*
* <p> File locks are held on behalf of the entire Java virtual machine.
* They are not suitable for controlling access to a file by multiple
* threads within the same virtual machine.
*
* @param position
* The position at which the locked region is to start; must be
* non-negative
* @param size
* The size of the locked region; must be non-negative, and the sum
* {@code position}&nbsp;+&nbsp;{@code size} must be non-negative
* @param shared
* {@code true} to request a shared lock, in which case this
* channel must be open for reading (and possibly writing);
* {@code false} to request an exclusive lock, in which case this
* channel must be open for writing (and possibly reading)
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
* The handler for consuming the result; can be {@code null}
*
* @return a {@code Future} object representing the pending result
*
* @throws OverlappingFileLockException
* If a lock that overlaps the requested region is already held by
* this Java virtual machine, or there is already a pending attempt
* to lock an overlapping region
* @throws IllegalArgumentException
* If the preconditions on the parameters do not hold
* @throws NonReadableChannelException
* If {@code shared} is true this channel but was not opened for reading
* @throws NonWritableChannelException
* If {@code shared} is false but this channel was not opened for writing
* @throws ShutdownChannelGroupException
* If a handler is specified, the channel is closed, and the channel
* was originally created with its own thread pool
*/
public abstract <A> Future<FileLock> lock(long position,
long size,
boolean shared,
A attachment,
CompletionHandler<FileLock,? super A> handler);
/**
* Acquires an exclusive lock on this channel's file.
*
* <p> This method initiates an operation to acquire an exclusive lock on this
* channel's file. The method returns a {@code Future} representing
* the pending result of the operation. Its {@link Future#get() get}
* method returns the {@link FileLock} on successful completion.
*
* <p> An invocation of this method of the form {@code ch.lock(att,handler)}
* behaves in exactly the same way as the invocation
* <pre>
* ch.{@link #lock(long,long,boolean,Object,CompletionHandler) lock}(0L, Long.MAX_VALUE, false, att, handler)
* </pre>
*
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
* The handler for consuming the result; can be {@code null}
*
* @return a {@code Future} object representing the pending result
*
* @throws OverlappingFileLockException
* If a lock is already held by this Java virtual machine, or there
* is already a pending attempt to lock a region
* @throws NonWritableChannelException
* If this channel was not opened for writing
* @throws ShutdownChannelGroupException
* If a handler is specified, the channel is closed, and the channel
* was originally created with its own thread pool
*/
public final <A> Future<FileLock> lock(A attachment,
CompletionHandler<FileLock,? super A> handler)
{
return lock(0L, Long.MAX_VALUE, false, attachment, handler);
}
/**
* Acquires an exclusive lock on this channel's file.
*
* <p> This method initiates an operation to acquire an exclusive lock on this
* channel's file. The method returns a {@code Future} representing the
* pending result of the operation. Its {@link Future#get() get} method
* returns the {@link FileLock} on successful completion.
*
* <p> An invocation of this method behaves in exactly the same way as the
* invocation
* <pre>
* ch.{@link #lock(long,long,boolean,Object,CompletionHandler) lock}(0L, Long.MAX_VALUE, false, null, null)
* </pre>
*
* @return A {@code Future} object representing the pending result
*
* @throws OverlappingFileLockException
* If a lock is already held by this Java virtual machine, or there
* is already a pending attempt to lock a region
* @throws NonWritableChannelException
* If this channel was not opened for writing
*/
public final Future<FileLock> lock() {
return lock(0L, Long.MAX_VALUE, false, null, null);
}
/**
* Attempts to acquire a lock on the given region of this channel's file.
*
* <p> This method does not block. An invocation always returns immediately,
* either having acquired a lock on the requested region or having failed to
* do so. If it fails to acquire a lock because an overlapping lock is held
* by another program then it returns {@code null}. If it fails to acquire
* a lock for any other reason then an appropriate exception is thrown.
*
* @param position
* The position at which the locked region is to start; must be
* non-negative
*
* @param size
* The size of the locked region; must be non-negative, and the sum
* {@code position}&nbsp;+&nbsp;{@code size} must be non-negative
*
* @param shared
* {@code true} to request a shared lock,
* {@code false} to request an exclusive lock
*
* @return A lock object representing the newly-acquired lock,
* or {@code null} if the lock could not be acquired
* because another program holds an overlapping lock
*
* @throws IllegalArgumentException
* If the preconditions on the parameters do not hold
* @throws ClosedChannelException
* If this channel is closed
* @throws OverlappingFileLockException
* If a lock that overlaps the requested region is already held by
* this Java virtual machine, or if another thread is already
* blocked in this method and is attempting to lock an overlapping
* region of the same file
* @throws NonReadableChannelException
* If {@code shared} is true this channel but was not opened for reading
* @throws NonWritableChannelException
* If {@code shared} is false but this channel was not opened for writing
*
* @throws IOException
* If some other I/O error occurs
*
* @see #lock(Object,CompletionHandler)
* @see #lock(long,long,boolean,Object,CompletionHandler)
* @see #tryLock()
*/
public abstract FileLock tryLock(long position, long size, boolean shared)
throws IOException;
/**
* Attempts to acquire an exclusive lock on this channel's file.
*
* <p> An invocation of this method of the form {@code ch.tryLock()}
* behaves in exactly the same way as the invocation
*
* <pre>
* ch.{@link #tryLock(long,long,boolean) tryLock}(0L, Long.MAX_VALUE, false) </pre>
*
* @return A lock object representing the newly-acquired lock,
* or {@code null} if the lock could not be acquired
* because another program holds an overlapping lock
*
* @throws ClosedChannelException
* If this channel is closed
* @throws OverlappingFileLockException
* If a lock that overlaps the requested region is already held by
* this Java virtual machine, or if another thread is already
* blocked in this method and is attempting to lock an overlapping
* region
* @throws NonWritableChannelException
* If {@code shared} is false but this channel was not opened for writing
*
* @throws IOException
* If some other I/O error occurs
*
* @see #lock(Object,CompletionHandler)
* @see #lock(long,long,boolean,Object,CompletionHandler)
* @see #tryLock(long,long,boolean)
*/
public final FileLock tryLock() throws IOException {
return tryLock(0L, Long.MAX_VALUE, false);
}
/**
* Reads a sequence of bytes from this channel into the given buffer,
* starting at the given file position.
*
* <p> This method initiates the reading of a sequence of bytes from this
* channel into the given buffer, starting at the given file position. This
* method returns a {@code Future} representing the pending result of the
* operation. The Future's {@link Future#get() get} method returns the
* number of bytes read or {@code -1} if the given position is greater than
* or equal to the file's size at the time that the read is attempted.
*
* <p> This method works in the same manner as the {@link
* AsynchronousByteChannel#read(ByteBuffer,Object,CompletionHandler)}
* method, except that bytes are read starting at the given file position.
* If the given file position is greater than the file's size at the time
* that the read is attempted then no bytes are read.
*
* @param dst
* The buffer into which bytes are to be transferred
* @param position
* The file position at which the transfer is to begin;
* must be non-negative
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
* The handler for consuming the result; can be {@code null}
*
* @return A {@code Future} object representing the pending result
*
* @throws IllegalArgumentException
* If the position is negative or the buffer is read-only
* @throws NonReadableChannelException
* If this channel was not opened for reading
* @throws ShutdownChannelGroupException
* If a handler is specified, the channel is closed, and the channel
* was originally created with its own thread pool
*/
public abstract <A> Future<Integer> read(ByteBuffer dst,
long position,
A attachment,
CompletionHandler<Integer,? super A> handler);
/**
* Reads a sequence of bytes from this channel into the given buffer,
* starting at the given file position.
*
* <p> This method initiates the reading of a sequence of bytes from this
* channel into the given buffer, starting at the given file position. This
* method returns a {@code Future} representing the pending result of the
* operation. The Future's {@link Future#get() get} method returns the
* number of bytes read or {@code -1} if the given position is greater
* than or equal to the file's size at the time that the read is attempted.
*
* <p> This method is equivalent to invoking {@link
* #read(ByteBuffer,long,Object,CompletionHandler)} with the {@code attachment}
* and handler parameters set to {@code null}.
*
* @param dst
* The buffer into which bytes are to be transferred
* @param position
* The file position at which the transfer is to begin;
* must be non-negative
*
* @return A {@code Future} object representing the pending result
*
* @throws IllegalArgumentException
* If the position is negative or the buffer is read-only
* @throws NonReadableChannelException
* If this channel was not opened for reading
*/
public final Future<Integer> read(ByteBuffer dst, long position) {
return read(dst, position, null, null);
}
/**
* Writes a sequence of bytes to this channel from the given buffer, starting
* at the given file position.
*
* <p> This method initiates the writing of a sequence of bytes to this channel
* from the given buffer, starting at the given file position. The method
* returns a {@code Future} representing the pending result of the write
* operation. The Future's {@link Future#get() get} method returns the
* number of bytes written.
*
* <p> This method works in the same manner as the {@link
* AsynchronousByteChannel#write(ByteBuffer,Object,CompletionHandler)}
* method, except that bytes are written starting at the given file position.
* If the given position is greater than the file's size, at the time that
* the write is attempted, then the file will be grown to accommodate the new
* bytes; the values of any bytes between the previous end-of-file and the
* newly-written bytes are unspecified.
*
* @param src
* The buffer from which bytes are to be transferred
* @param position
* The file position at which the transfer is to begin;
* must be non-negative
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
* The handler for consuming the result; can be {@code null}
*
* @return A {@code Future} object representing the pending result
*
* @throws IllegalArgumentException
* If the position is negative
* @throws NonWritableChannelException
* If this channel was not opened for writing
* @throws ShutdownChannelGroupException
* If a handler is specified, the channel is closed, and the channel
* was originally created with its own thread pool
*/
public abstract <A> Future<Integer> write(ByteBuffer src,
long position,
A attachment,
CompletionHandler<Integer,? super A> handler);
/**
* Writes a sequence of bytes to this channel from the given buffer, starting
* at the given file position.
*
* <p> This method initiates the writing of a sequence of bytes to this channel
* from the given buffer, starting at the given file position. The method
* returns a {@code Future} representing the pending result of the write
* operation. The Future's {@link Future#get() get} method returns the
* number of bytes written.
*
* <p> This method is equivalent to invoking {@link
* #write(ByteBuffer,long,Object,CompletionHandler)} with the {@code attachment}
* and handler parameters set to {@code null}.
*
* @param src
* The buffer from which bytes are to be transferred
* @param position
* The file position at which the transfer is to begin;
* must be non-negative
*
* @return A {@code Future} object representing the pending result
*
* @throws IllegalArgumentException
* If the position is negative
* @throws NonWritableChannelException
* If this channel was not opened for writing
*/
public final Future<Integer> write(ByteBuffer src, long position) {
return write(src, position, null, null);
}
}

303
jdk/src/share/classes/java/nio/channels/AsynchronousServerSocketChannel.java Normal file
View file

@ -0,0 +1,303 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.channels;
import java.nio.channels.spi.*;
import java.net.SocketOption;
import java.net.SocketAddress;
import java.util.concurrent.Future;
import java.io.IOException;
/**
* An asynchronous channel for stream-oriented listening sockets.
*
* <p> An asynchronous server-socket channel is created by invoking the
* {@link #open open} method of this class.
* A newly-created asynchronous server-socket channel is open but not yet bound.
* It can be bound to a local address and configured to listen for connections
* by invoking the {@link #bind(SocketAddress,int) bind} method. Once bound,
* the {@link #accept(Object,CompletionHandler) accept} method
* is used to initiate the accepting of connections to the channel's socket.
* An attempt to invoke the <tt>accept</tt> method on an unbound channel will
* cause a {@link NotYetBoundException} to be thrown.
*
* <p> Channels of this type are safe for use by multiple concurrent threads
* though at most one accept operation can be outstanding at any time.
* If a thread initiates an accept operation before a previous accept operation
* has completed then an {@link AcceptPendingException} will be thrown.
*
* <p> Socket options are configured using the {@link #setOption(SocketOption,Object)
* setOption} method. Channels of this type support the following options:
* <blockquote>
* <table border>
* <tr>
* <th>Option Name</th>
* <th>Description</th>
* </tr>
* <tr>
* <td> {@link java.net.StandardSocketOption#SO_RCVBUF SO_RCVBUF} </td>
* <td> The size of the socket receive buffer </td>
* </tr>
* <tr>
* <td> {@link java.net.StandardSocketOption#SO_REUSEADDR SO_REUSEADDR} </td>
* <td> Re-use address </td>
* </tr>
* </table>
* </blockquote>
* Additional (implementation specific) options may also be supported.
*
* <p> <b>Usage Example:</b>
* <pre>
* final AsynchronousServerSocketChannel listener =
* AsynchronousServerSocketChannel.open().bind(new InetSocketAddress(5000));
*
* listener.accept(null, new CompletionHandler&lt;AsynchronousSocketChannel,Void&gt;() {
* public void completed(AsynchronousSocketChannel ch, Void att) {
* // accept the next connection
* listener.accept(null, this);
*
* // handle this connection
* handle(ch);
* }
* public void failed(Throwable exc, Void att) {
* ...
* }
* public void cancelled(Void att) {
* ...
* }
* });
* </pre>
*
* @since 1.7
*/
public abstract class AsynchronousServerSocketChannel
implements AsynchronousChannel, NetworkChannel
{
private final AsynchronousChannelProvider provider;
/**
* Initializes a new instance of this class.
*/
protected AsynchronousServerSocketChannel(AsynchronousChannelProvider provider) {
this.provider = provider;
}
/**
* Returns the provider that created this channel.
*/
public final AsynchronousChannelProvider provider() {
return provider;
}
/**
* Opens an asynchronous server-socket channel.
*
* <p> The new channel is created by invoking the {@link
* java.nio.channels.spi.AsynchronousChannelProvider#openAsynchronousServerSocketChannel
* openAsynchronousServerSocketChannel} method on the {@link
* java.nio.channels.spi.AsynchronousChannelProvider} object that created
* the given group. If the group parameter is <tt>null</tt> then the
* resulting channel is created by the system-wide default provider, and
* bound to the <em>default group</em>.
*
* @param group
* The group to which the newly constructed channel should be bound,
* or <tt>null</tt> for the default group
*
* @return A new asynchronous server socket channel
*
* @throws ShutdownChannelGroupException
* If the channel group is shutdown
* @throws IOException
* If an I/O error occurs
*/
public static AsynchronousServerSocketChannel open(AsynchronousChannelGroup group)
throws IOException
{
AsynchronousChannelProvider provider = (group == null) ?
AsynchronousChannelProvider.provider() : group.provider();
return provider.openAsynchronousServerSocketChannel(group);
}
/**
* Opens an asynchronous server-socket channel.
*
* <p> This method returns an asynchronous server socket channel that is
* bound to the <em>default group</em>. This method is equivalent to evaluating
* the expression:
* <blockquote><pre>
* open((AsynchronousChannelGroup)null);
* </pre></blockquote>
*
* @return A new asynchronous server socket channel
*
* @throws IOException
* If an I/O error occurs
*/
public static AsynchronousServerSocketChannel open()
throws IOException
{
return open(null);
}
/**
* Binds the channel's socket to a local address and configures the socket to
* listen for connections.
*
* <p> An invocation of this method is equivalent to the following:
* <blockquote><pre>
* bind(local, 0);
* </pre></blockquote>
*
* @param local
* The local address to bind the socket, or <tt>null</tt> to bind
* to an automatically assigned socket address
*
* @return This channel
*
* @throws AlreadyBoundException {@inheritDoc}
* @throws UnsupportedAddressTypeException {@inheritDoc}
* @throws SecurityException {@inheritDoc}
* @throws ClosedChannelException {@inheritDoc}
* @throws IOException {@inheritDoc}
*/
public final AsynchronousServerSocketChannel bind(SocketAddress local)
throws IOException
{
return bind(local, 0);
}
/**
* Binds the channel's socket to a local address and configures the socket to
* listen for connections.
*
* <p> This method is used to establish an association between the socket and
* a local address. Once an association is established then the socket remains
* bound until the associated channel is closed.
*
* <p> The {@code backlog} parameter is the maximum number of pending
* connections on the socket. Its exact semantics are implementation specific.
* In particular, an implementation may impose a maximum length or may choose
* to ignore the parameter altogther. If the {@code backlog} parameter has
* the value {@code 0}, or a negative value, then an implementation specific
* default is used.
*
* @param local
* The local address to bind the socket, or {@code null} to bind
* to an automatically assigned socket address
* @param backlog
* The maximum number of pending connections
*
* @return This channel
*
* @throws AlreadyBoundException
* If the socket is already bound
* @throws UnsupportedAddressTypeException
* If the type of the given address is not supported
* @throws SecurityException
* If a security manager has been installed and its {@link
* SecurityManager#checkListen checkListen} method denies the operation
* @throws ClosedChannelException
* If the channel is closed
* @throws IOException
* If some other I/O error occurs
*/
public abstract AsynchronousServerSocketChannel bind(SocketAddress local, int backlog)
throws IOException;
/**
* @throws IllegalArgumentException {@inheritDoc}
* @throws ClosedChannelException {@inheritDoc}
* @throws IOException {@inheritDoc}
*/
public abstract <T> AsynchronousServerSocketChannel setOption(SocketOption<T> name, T value)
throws IOException;
/**
* Accepts a connection.
*
* <p> This method initiates accepting a connection made to this channel's
* socket, returning a {@link Future} representing the pending result
* of the operation. The {@code Future}'s {@link Future#get() get}
* method will return the {@link AsynchronousSocketChannel} for the new
* connection on successful completion.
*
* <p> When a new connection is accepted then the resulting {@code
* AsynchronousSocketChannel} will be bound to the same {@link
* AsynchronousChannelGroup} as this channel. If the group is {@link
* AsynchronousChannelGroup#isShutdown shutdown} and a connection is accepted,
* then the connection is closed, and the operation completes with an {@code
* IOException} and cause {@link ShutdownChannelGroupException}.
*
* <p> To allow for concurrent handling of new connections, the completion
* handler is not invoked directly by the initiating thread when a new
* connection is accepted immediately (see <a
* href="AsynchronousChannelGroup.html#threading">Threading<a>).
*
* <p> If a security manager has been installed then it verifies that the
* address and port number of the connection's remote endpoint are permitted
* by the security manager's {@link SecurityManager#checkAccept checkAccept}
* method. The permission check is performed with privileges that are restricted
* by the calling context of this method. If the permission check fails then
* the connection is closed and the operation completes with a {@link
* SecurityException}.
*
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
* The handler for consuming the result; can be {@code null}
*
* @return an <tt>Future</tt> object representing the pending result
*
* @throws AcceptPendingException
* If an accept operation is already in progress on this channel
* @throws NotYetBoundException
* If this channel's socket has not yet been bound
* @throws ShutdownChannelGroupException
* If a handler is specified, and the channel group is shutdown
*/
public abstract <A> Future<AsynchronousSocketChannel>
accept(A attachment, CompletionHandler<AsynchronousSocketChannel,? super A> handler);
/**
* Accepts a connection.
*
* <p> This method is equivalent to invoking {@link
* #accept(Object,CompletionHandler)} with the {@code attachment}
* and {@code handler} parameters set to {@code null}.
*
* @return an <tt>Future</tt> object representing the pending result
*
* @throws AcceptPendingException
* If an accept operation is already in progress on this channel
* @throws NotYetBoundException
* If this channel's socket has not yet been bound
*/
public final Future<AsynchronousSocketChannel> accept() {
return accept(null, null);
}
}

670
jdk/src/share/classes/java/nio/channels/AsynchronousSocketChannel.java Normal file
View file

@ -0,0 +1,670 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.channels;
import java.nio.channels.spi.*;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.Future;
import java.io.IOException;
import java.net.SocketOption;
import java.net.SocketAddress;
import java.nio.ByteBuffer;
/**
* An asynchronous channel for stream-oriented connecting sockets.
*
* <p> Asynchronous socket channels are created in one of two ways. A newly-created
* {@code AsynchronousSocketChannel} is created by invoking one of the {@link
* #open open} methods defined by this class. A newly-created channel is open but
* not yet connected. A connected {@code AsynchronousSocketChannel} is created
* when a connection is made to the socket of an {@link AsynchronousServerSocketChannel}.
* It is not possible to create an asynchronous socket channel for an arbitrary,
* pre-existing {@link java.net.Socket socket}.
*
* <p> A newly-created channel is connected by invoking its {@link #connect connect}
* method; once connected, a channel remains connected until it is closed. Whether
* or not a socket channel is connected may be determined by invoking its {@link
* #getRemoteAddress getRemoteAddress} method. An attempt to invoke an I/O
* operation upon an unconnected channel will cause a {@link NotYetConnectedException}
* to be thrown.
*
* <p> Channels of this type are safe for use by multiple concurrent threads.
* They support concurrent reading and writing, though at most one read operation
* and one write operation can be outstanding at any time.
* If a thread initiates a read operation before a previous read operation has
* completed then a {@link ReadPendingException} will be thrown. Similarly, an
* attempt to initiate a write operation before a previous write has completed
* will throw a {@link WritePendingException}.
*
* <p> Socket options are configured using the {@link #setOption(SocketOption,Object)
* setOption} method. Asynchronous socket channels support the following options:
* <blockquote>
* <table border>
* <tr>
* <th>Option Name</th>
* <th>Description</th>
* </tr>
* <tr>
* <td> {@link java.net.StandardSocketOption#SO_SNDBUF SO_SNDBUF} </td>
* <td> The size of the socket send buffer </td>
* </tr>
* <tr>
* <td> {@link java.net.StandardSocketOption#SO_RCVBUF SO_RCVBUF} </td>
* <td> The size of the socket receive buffer </td>
* </tr>
* <tr>
* <td> {@link java.net.StandardSocketOption#SO_KEEPALIVE SO_KEEPALIVE} </td>
* <td> Keep connection alive </td>
* </tr>
* <tr>
* <td> {@link java.net.StandardSocketOption#SO_REUSEADDR SO_REUSEADDR} </td>
* <td> Re-use address </td>
* </tr>
* <tr>
* <td> {@link java.net.StandardSocketOption#TCP_NODELAY TCP_NODELAY} </td>
* <td> Disable the Nagle algorithm </td>
* </tr>
* </table>
* </blockquote>
* Additional (implementation specific) options may also be supported.
*
* <h4>Timeouts</h4>
*
* <p> The {@link #read(ByteBuffer,long,TimeUnit,Object,CompletionHandler) read}
* and {@link #write(ByteBuffer,long,TimeUnit,Object,CompletionHandler) write}
* methods defined by this class allow a timeout to be specified when initiating
* a read or write operation. If the timeout elapses before an operation completes
* then the operation completes with the exception {@link
* InterruptedByTimeoutException}. A timeout may leave the channel, or the
* underlying connection, in an inconsistent state. Where the implementation
* cannot guarantee that bytes have not been read from the channel then it puts
* the channel into an implementation specific <em>error state</em>. A subsequent
* attempt to initiate a {@code read} operation causes an unspecified runtime
* exception to be thrown. Similarly if a {@code write} operation times out and
* the implementation cannot guarantee bytes have not been written to the
* channel then further attempts to {@code write} to the channel cause an
* unspecified runtime exception to be thrown. When a timeout elapses then the
* state of the {@link ByteBuffer}, or the sequence of buffers, for the I/O
* operation is not defined. Buffers should be discarded or at least care must
* be taken to ensure that the buffers are not accessed while the channel remains
* open.
*
* @since 1.7
*/
public abstract class AsynchronousSocketChannel
implements AsynchronousByteChannel, NetworkChannel
{
private final AsynchronousChannelProvider provider;
/**
* Initializes a new instance of this class.
*/
protected AsynchronousSocketChannel(AsynchronousChannelProvider provider) {
this.provider = provider;
}
/**
* Returns the provider that created this channel.
*/
public final AsynchronousChannelProvider provider() {
return provider;
}
/**
* Opens an asynchronous socket channel.
*
* <p> The new channel is created by invoking the {@link
* AsynchronousChannelProvider#openAsynchronousSocketChannel
* openAsynchronousSocketChannel} method on the {@link
* AsynchronousChannelProvider} that created the group. If the group parameter
* is {@code null} then the resulting channel is created by the system-wide
* default provider, and bound to the <em>default group</em>.
*
* @param group
* The group to which the newly constructed channel should be bound,
* or {@code null} for the default group
*
* @return A new asynchronous socket channel
*
* @throws ShutdownChannelGroupException
* If the channel group is shutdown
* @throws IOException
* If an I/O error occurs
*/
public static AsynchronousSocketChannel open(AsynchronousChannelGroup group)
throws IOException
{
AsynchronousChannelProvider provider = (group == null) ?
AsynchronousChannelProvider.provider() : group.provider();
return provider.openAsynchronousSocketChannel(group);
}
/**
* Opens an asynchronous socket channel.
*
* <p> This method returns an asynchronous socket channel that is bound to
* the <em>default group</em>.This method is equivalent to evaluating the
* expression:
* <blockquote><pre>
* open((AsynchronousChannelGroup)null);
* </pre></blockquote>
*
* @return A new asynchronous socket channel
*
* @throws IOException
* If an I/O error occurs
*/
public static AsynchronousSocketChannel open()
throws IOException
{
return open(null);
}
// -- socket options and related --
/**
* @throws ConnectionPendingException
* If a connection operation is already in progress on this channel
* @throws AlreadyBoundException {@inheritDoc}
* @throws UnsupportedAddressTypeException {@inheritDoc}
* @throws ClosedChannelException {@inheritDoc}
* @throws IOException {@inheritDoc}
*/
@Override
public abstract AsynchronousSocketChannel bind(SocketAddress local)
throws IOException;
/**
* @throws IllegalArgumentException {@inheritDoc}
* @throws ClosedChannelException {@inheritDoc}
* @throws IOException {@inheritDoc}
*/
@Override
public abstract <T> AsynchronousSocketChannel setOption(SocketOption<T> name, T value)
throws IOException;
/**
* Shutdown the connection for reading without closing the channel.
*
* <p> Once shutdown for reading then further reads on the channel will
* return {@code -1}, the end-of-stream indication. If the input side of the
* connection is already shutdown then invoking this method has no effect.
* The effect on an outstanding read operation is system dependent and
* therefore not specified. The effect, if any, when there is data in the
* socket receive buffer that has not been read, or data arrives subsequently,
* is also system dependent.
*
* @return The channel
*
* @throws NotYetConnectedException
* If this channel is not yet connected
* @throws ClosedChannelException
* If this channel is closed
* @throws IOException
* If some other I/O error occurs
*/
public abstract AsynchronousSocketChannel shutdownInput() throws IOException;
/**
* Shutdown the connection for writing without closing the channel.
*
* <p> Once shutdown for writing then further attempts to write to the
* channel will throw {@link ClosedChannelException}. If the output side of
* the connection is already shutdown then invoking this method has no
* effect. The effect on an outstanding write operation is system dependent
* and therefore not specified.
*
* @return The channel
*
* @throws NotYetConnectedException
* If this channel is not yet connected
* @throws ClosedChannelException
* If this channel is closed
* @throws IOException
* If some other I/O error occurs
*/
public abstract AsynchronousSocketChannel shutdownOutput() throws IOException;
// -- state --
/**
* Returns the remote address to which this channel's socket is connected.
*
* <p> Where the channel is bound and connected to an Internet Protocol
* socket address then the return value from this method is of type {@link
* java.net.InetSocketAddress}.
*
* @return The remote address; {@code null} if the channel's socket is not
* connected
*
* @throws ClosedChannelException
* If the channel is closed
* @throws IOException
* If an I/O error occurs
*/
public abstract SocketAddress getRemoteAddress() throws IOException;
// -- asynchronous operations --
/**
* Connects this channel.
*
* <p> This method initiates an operation to connect this channel, returning
* a {@code Future} representing the pending result of the operation. If
* the connection is successfully established then the {@code Future}'s
* {@link Future#get() get} method will return {@code null}. If the
* connection cannot be established then the channel is closed. In that case,
* invoking the {@code get} method throws {@link
* java.util.concurrent.ExecutionException} with an {@code IOException} as
* the cause.
*
* <p> This method performs exactly the same security checks as the {@link
* java.net.Socket} class. That is, if a security manager has been
* installed then this method verifies that its {@link
* java.lang.SecurityManager#checkConnect checkConnect} method permits
* connecting to the address and port number of the given remote endpoint.
*
* @param remote
* The remote address to which this channel is to be connected
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
* The handler for consuming the result; can be {@code null}
*
* @return A {@code Future} object representing the pending result
*
* @throws UnresolvedAddressException
* If the given remote address is not fully resolved
* @throws UnsupportedAddressTypeException
* If the type of the given remote address is not supported
* @throws AlreadyConnectedException
* If this channel is already connected
* @throws ConnectionPendingException
* If a connection operation is already in progress on this channel
* @throws ShutdownChannelGroupException
* If a handler is specified, and the channel group is shutdown
* @throws SecurityException
* If a security manager has been installed
* and it does not permit access to the given remote endpoint
*
* @see #getRemoteAddress
*/
public abstract <A> Future<Void> connect(SocketAddress remote,
A attachment,
CompletionHandler<Void,? super A> handler);
/**
* Connects this channel.
*
* <p> This method is equivalent to invoking {@link
* #connect(SocketAddress,Object,CompletionHandler)} with the {@code attachment}
* and handler parameters set to {@code null}.
*
* @param remote
* The remote address to which this channel is to be connected
*
* @return A {@code Future} object representing the pending result
*
* @throws UnresolvedAddressException
* If the given remote address is not fully resolved
* @throws UnsupportedAddressTypeException
* If the type of the given remote address is not supported
* @throws AlreadyConnectedException
* If this channel is already connected
* @throws ConnectionPendingException
* If a connection operation is already in progress on this channel
* @throws SecurityException
* If a security manager has been installed
* and it does not permit access to the given remote endpoint
*/
public final Future<Void> connect(SocketAddress remote) {
return connect(remote, null, null);
}
/**
* Reads a sequence of bytes from this channel into the given buffer.
*
* <p> This method initiates the reading of a sequence of bytes from this
* channel into the given buffer, returning a {@code Future} representing
* the pending result of the operation. The {@code Future}'s {@link
* Future#get() get} method returns the number of bytes read or {@code -1}
* if all bytes have been read and channel has reached end-of-stream.
*
* <p> If a timeout is specified and the timeout elapses before the operation
* completes then the operation completes with the exception {@link
* InterruptedByTimeoutException}. Where a timeout occurs, and the
* implementation cannot guarantee that bytes have not been read, or will not
* be read from the channel into the given buffer, then further attempts to
* read from the channel will cause an unspecific runtime exception to be
* thrown.
*
* <p> Otherwise this method works in the same manner as the {@link
* AsynchronousByteChannel#read(ByteBuffer,Object,CompletionHandler)}
* method.
*
* @param dst
* The buffer into which bytes are to be transferred
* @param timeout
* The timeout, or {@code 0L} for no timeout
* @param unit
* The time unit of the {@code timeout} argument
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
* The handler for consuming the result; can be {@code null}
*
* @return A {@code Future} object representing the pending result
*
* @throws IllegalArgumentException
* If the {@code timeout} parameter is negative or the buffer is
* read-only
* @throws ReadPendingException
* If a read operation is already in progress on this channel
* @throws NotYetConnectedException
* If this channel is not yet connected
* @throws ShutdownChannelGroupException
* If a handler is specified, and the channel group is shutdown
*/
public abstract <A> Future<Integer> read(ByteBuffer dst,
long timeout,
TimeUnit unit,
A attachment,
CompletionHandler<Integer,? super A> handler);
/**
* @throws IllegalArgumentException {@inheritDoc}
* @throws ReadPendingException {@inheritDoc}
* @throws NotYetConnectedException
* If this channel is not yet connected
* @throws ShutdownChannelGroupException
* If a handler is specified, and the channel group is shutdown
*/
@Override
public final <A> Future<Integer> read(ByteBuffer dst,
A attachment,
CompletionHandler<Integer,? super A> handler)
{
return read(dst, 0L, TimeUnit.MILLISECONDS, attachment, handler);
}
/**
* @throws IllegalArgumentException {@inheritDoc}
* @throws ReadPendingException {@inheritDoc}
* @throws NotYetConnectedException
* If this channel is not yet connected
*/
@Override
public final Future<Integer> read(ByteBuffer dst) {
return read(dst, 0L, TimeUnit.MILLISECONDS, null, null);
}
/**
* Reads a sequence of bytes from this channel into a subsequence of the
* given buffers. This operation, sometimes called a <em>scattering read</em>,
* is often useful when implementing network protocols that group data into
* segments consisting of one or more fixed-length headers followed by a
* variable-length body.
*
* <p> This method initiates a read of up to <i>r</i> bytes from this channel,
* where <i>r</i> is the total number of bytes remaining in the specified
* subsequence of the given buffer array, that is,
*
* <blockquote><pre>
* dsts[offset].remaining()
* + dsts[offset+1].remaining()
* + ... + dsts[offset+length-1].remaining()</pre></blockquote>
*
* at the moment that the read is attempted.
*
* <p> Suppose that a byte sequence of length <i>n</i> is read, where
* <tt>0</tt>&nbsp;<tt>&lt;</tt>&nbsp;<i>n</i>&nbsp;<tt>&lt;=</tt>&nbsp;<i>r</i>.
* Up to the first <tt>dsts[offset].remaining()</tt> bytes of this sequence
* are transferred into buffer <tt>dsts[offset]</tt>, up to the next
* <tt>dsts[offset+1].remaining()</tt> bytes are transferred into buffer
* <tt>dsts[offset+1]</tt>, and so forth, until the entire byte sequence
* is transferred into the given buffers. As many bytes as possible are
* transferred into each buffer, hence the final position of each updated
* buffer, except the last updated buffer, is guaranteed to be equal to
* that buffer's limit. The underlying operating system may impose a limit
* on the number of buffers that may be used in an I/O operation. Where the
* number of buffers (with bytes remaining), exceeds this limit, then the
* I/O operation is performed with the maximum number of buffers allowed by
* the operating system.
*
* <p> The return value from this method is a {@code Future} representing
* the pending result of the operation. The {@code Future}'s {@link
* Future#get() get} method returns the number of bytes read or {@code -1L}
* if all bytes have been read and the channel has reached end-of-stream.
*
* <p> If a timeout is specified and the timeout elapses before the operation
* completes then it completes with the exception {@link
* InterruptedByTimeoutException}. Where a timeout occurs, and the
* implementation cannot guarantee that bytes have not been read, or will not
* be read from the channel into the given buffers, then further attempts to
* read from the channel will cause an unspecific runtime exception to be
* thrown.
*
* @param dsts
* The buffers into which bytes are to be transferred
* @param offset
* The offset within the buffer array of the first buffer into which
* bytes are to be transferred; must be non-negative and no larger than
* {@code dsts.length}
* @param length
* The maximum number of buffers to be accessed; must be non-negative
* and no larger than {@code dsts.length - offset}
* @param timeout
* The timeout, or {@code 0L} for no timeout
* @param unit
* The time unit of the {@code timeout} argument
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
* The handler for consuming the result; can be {@code null}
*
* @return A {@code Future} object representing the pending result
*
* @throws IndexOutOfBoundsException
* If the pre-conditions for the {@code offset} and {@code length}
* parameter aren't met
* @throws IllegalArgumentException
* If the {@code timeout} parameter is negative, or a buffer is
* read-only
* @throws ReadPendingException
* If a read operation is already in progress on this channel
* @throws NotYetConnectedException
* If this channel is not yet connected
* @throws ShutdownChannelGroupException
* If a handler is specified, and the channel group is shutdown
*/
public abstract <A> Future<Long> read(ByteBuffer[] dsts,
int offset,
int length,
long timeout,
TimeUnit unit,
A attachment,
CompletionHandler<Long,? super A> handler);
/**
* Writes a sequence of bytes to this channel from the given buffer.
*
* <p> This method initiates the writing of a sequence of bytes to this channel
* from the given buffer, returning a {@code Future} representing the
* pending result of the operation. The {@code Future}'s {@link Future#get()
* get} method will return the number of bytes written.
*
* <p> If a timeout is specified and the timeout elapses before the operation
* completes then it completes with the exception {@link
* InterruptedByTimeoutException}. Where a timeout occurs, and the
* implementation cannot guarantee that bytes have not been written, or will
* not be written to the channel from the given buffer, then further attempts
* to write to the channel will cause an unspecific runtime exception to be
* thrown.
*
* <p> Otherwise this method works in the same manner as the {@link
* AsynchronousByteChannel#write(ByteBuffer,Object,CompletionHandler)}
* method.
*
* @param src
* The buffer from which bytes are to be retrieved
* @param timeout
* The timeout, or {@code 0L} for no timeout
* @param unit
* The time unit of the {@code timeout} argument
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
* The handler for consuming the result; can be {@code null}
*
* @return A {@code Future} object representing the pending result
*
* @throws IllegalArgumentException
* If the {@code timeout} parameter is negative
* @throws WritePendingException
* If a write operation is already in progress on this channel
* @throws NotYetConnectedException
* If this channel is not yet connected
* @throws ShutdownChannelGroupException
* If a handler is specified, and the channel group is shutdown
*/
public abstract <A> Future<Integer> write(ByteBuffer src,
long timeout,
TimeUnit unit,
A attachment,
CompletionHandler<Integer,? super A> handler);
/**
* @throws WritePendingException {@inheritDoc}
* @throws NotYetConnectedException
* If this channel is not yet connected
* @throws ShutdownChannelGroupException
* If a handler is specified, and the channel group is shutdown
*/
@Override
public final <A> Future<Integer> write(ByteBuffer src,
A attachment,
CompletionHandler<Integer,? super A> handler)
{
return write(src, 0L, TimeUnit.MILLISECONDS, attachment, handler);
}
/**
* @throws WritePendingException {@inheritDoc}
* @throws NotYetConnectedException
* If this channel is not yet connected
*/
@Override
public final Future<Integer> write(ByteBuffer src) {
return write(src, 0L, TimeUnit.MILLISECONDS, null, null);
}
/**
* Writes a sequence of bytes to this channel from a subsequence of the given
* buffers. This operation, sometimes called a <em>gathering write</em>, is
* often useful when implementing network protocols that group data into
* segments consisting of one or more fixed-length headers followed by a
* variable-length body.
*
* <p> This method initiates a write of up to <i>r</i> bytes to this channel,
* where <i>r</i> is the total number of bytes remaining in the specified
* subsequence of the given buffer array, that is,
*
* <blockquote><pre>
* srcs[offset].remaining()
* + srcs[offset+1].remaining()
* + ... + srcs[offset+length-1].remaining()</pre></blockquote>
*
* at the moment that the write is attempted.
*
* <p> Suppose that a byte sequence of length <i>n</i> is written, where
* <tt>0</tt>&nbsp;<tt>&lt;</tt>&nbsp;<i>n</i>&nbsp;<tt>&lt;=</tt>&nbsp;<i>r</i>.
* Up to the first <tt>srcs[offset].remaining()</tt> bytes of this sequence
* are written from buffer <tt>srcs[offset]</tt>, up to the next
* <tt>srcs[offset+1].remaining()</tt> bytes are written from buffer
* <tt>srcs[offset+1]</tt>, and so forth, until the entire byte sequence is
* written. As many bytes as possible are written from each buffer, hence
* the final position of each updated buffer, except the last updated
* buffer, is guaranteed to be equal to that buffer's limit. The underlying
* operating system may impose a limit on the number of buffers that may be
* used in an I/O operation. Where the number of buffers (with bytes
* remaining), exceeds this limit, then the I/O operation is performed with
* the maximum number of buffers allowed by the operating system.
*
* <p> The return value from this method is a {@code Future} representing
* the pending result of the operation. The {@code Future}'s {@link
* Future#get() get} method will return the number of bytes written.
*
* <p> If a timeout is specified and the timeout elapses before the operation
* completes then it completes with the exception {@link
* InterruptedByTimeoutException}. Where a timeout occurs, and the
* implementation cannot guarantee that bytes have not been written, or will
* not be written to the channel from the given buffers, then further attempts
* to write to the channel will cause an unspecific runtime exception to be
* thrown.
*
* @param srcs
* The buffers from which bytes are to be retrieved
* @param offset
* The offset within the buffer array of the first buffer from which
* bytes are to be retrieved; must be non-negative and no larger
* than {@code srcs.length}
* @param length
* The maximum number of buffers to be accessed; must be non-negative
* and no larger than {@code srcs.length - offset}
* @param timeout
* The timeout, or {@code 0L} for no timeout
* @param unit
* The time unit of the {@code timeout} argument
* @param attachment
* The object to attach to the I/O operation; can be {@code null}
* @param handler
* The handler for consuming the result; can be {@code null}
*
* @return A {@code Future} object representing the pending result
*
* @throws IndexOutOfBoundsException
* If the pre-conditions for the {@code offset} and {@code length}
* parameter aren't met
* @throws IllegalArgumentException
* If the {@code timeout} parameter is negative
* @throws WritePendingException
* If a write operation is already in progress on this channel
* @throws NotYetConnectedException
* If this channel is not yet connected
* @throws ShutdownChannelGroupException
* If a handler is specified, and the channel group is shutdown
*/
public abstract <A> Future<Long> write(ByteBuffer[] srcs,
int offset,
int length,
long timeout,
TimeUnit unit,
A attachment,
CompletionHandler<Long,? super A> handler);
}

157
jdk/src/share/classes/java/nio/channels/Channels.java
View file

@ -1,5 +1,5 @@
/*
* Copyright 2000-2008 Sun Microsystems, Inc. All Rights Reserved.
* Copyright 2000-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -33,15 +33,12 @@ import java.io.Reader;
import java.io.Writer;
import java.io.IOException;
import java.nio.ByteBuffer;
import java.nio.CharBuffer;
import java.nio.BufferOverflowException;
import java.nio.BufferUnderflowException;
import java.nio.charset.Charset;
import java.nio.charset.CharsetDecoder;
import java.nio.charset.CharsetEncoder;
import java.nio.charset.CoderResult;
import java.nio.charset.UnsupportedCharsetException;
import java.nio.channels.spi.AbstractInterruptibleChannel;
import java.util.concurrent.ExecutionException;
import sun.nio.ch.ChannelInputStream;
import sun.nio.cs.StreamDecoder;
import sun.nio.cs.StreamEncoder;
@ -184,6 +181,155 @@ public final class Channels {
};
}
/**
* {@note new}
* Constructs a stream that reads bytes from the given channel.
*
* <p> The stream will not be buffered, and it will not support the {@link
* InputStream#mark mark} or {@link InputStream#reset reset} methods. The
* stream will be safe for access by multiple concurrent threads. Closing
* the stream will in turn cause the channel to be closed. </p>
*
* @param ch
* The channel from which bytes will be read
*
* @return A new input stream
*
* @since 1.7
*/
public static InputStream newInputStream(final AsynchronousByteChannel ch) {
checkNotNull(ch, "ch");
return new InputStream() {
private ByteBuffer bb = null;
private byte[] bs = null; // Invoker's previous array
private byte[] b1 = null;
@Override
public synchronized int read() throws IOException {
if (b1 == null)
b1 = new byte[1];
int n = this.read(b1);
if (n == 1)
return b1[0] & 0xff;
return -1;
}
@Override
public synchronized int read(byte[] bs, int off, int len)
throws IOException
{
if ((off < 0) || (off > bs.length) || (len < 0) ||
((off + len) > bs.length) || ((off + len) < 0)) {
throw new IndexOutOfBoundsException();
} else if (len == 0)
return 0;
ByteBuffer bb = ((this.bs == bs)
? this.bb
: ByteBuffer.wrap(bs));
bb.position(off);
bb.limit(Math.min(off + len, bb.capacity()));
this.bb = bb;
this.bs = bs;
boolean interrupted = false;
try {
for (;;) {
try {
return ch.read(bb).get();
} catch (ExecutionException ee) {
throw new IOException(ee.getCause());
} catch (InterruptedException ie) {
interrupted = true;
}
}
} finally {
if (interrupted)
Thread.currentThread().interrupt();
}
}
@Override
public void close() throws IOException {
ch.close();
}
};
}
/**
* {@note new}
* Constructs a stream that writes bytes to the given channel.
*
* <p> The stream will not be buffered. The stream will be safe for access
* by multiple concurrent threads. Closing the stream will in turn cause
* the channel to be closed. </p>
*
* @param ch
* The channel to which bytes will be written
*
* @return A new output stream
*
* @since 1.7
*/
public static OutputStream newOutputStream(final AsynchronousByteChannel ch) {
checkNotNull(ch, "ch");
return new OutputStream() {
private ByteBuffer bb = null;
private byte[] bs = null; // Invoker's previous array
private byte[] b1 = null;
@Override
public synchronized void write(int b) throws IOException {
if (b1 == null)
b1 = new byte[1];
b1[0] = (byte)b;
this.write(b1);
}
@Override
public synchronized void write(byte[] bs, int off, int len)
throws IOException
{
if ((off < 0) || (off > bs.length) || (len < 0) ||
((off + len) > bs.length) || ((off + len) < 0)) {
throw new IndexOutOfBoundsException();
} else if (len == 0) {
return;
}
ByteBuffer bb = ((this.bs == bs)
? this.bb
: ByteBuffer.wrap(bs));
bb.limit(Math.min(off + len, bb.capacity()));
bb.position(off);
this.bb = bb;
this.bs = bs;
boolean interrupted = false;
try {
while (bb.remaining() > 0) {
try {
ch.write(bb).get();
} catch (ExecutionException ee) {
throw new IOException(ee.getCause());
} catch (InterruptedException ie) {
interrupted = true;
}
}
} finally {
if (interrupted)
Thread.currentThread().interrupt();
}
}
@Override
public void close() throws IOException {
ch.close();
}
};
}
// -- Channels from streams --
@ -468,5 +614,4 @@ public final class Channels {
checkNotNull(csName, "csName");
return newWriter(ch, Charset.forName(csName).newEncoder(), -1);
}
}

77
jdk/src/share/classes/java/nio/channels/CompletionHandler.java Normal file
View file

@ -0,0 +1,77 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.channels;
/**
* A handler for consuming the result of an asynchronous I/O operation.
*
* <p> The asynchronous channels defined in this package allow a completion
* handler to be specified to consume the result of an asynchronous operation.
* The {@link #completed completed} method is invoked when the I/O operation
* completes successfully. The {@link #failed failed} method is invoked if the
* I/O operations fails. The {@link #cancelled cancelled} method is invoked when
* the I/O operation is cancelled by invoking the {@link
* java.util.concurrent.Future#cancel cancel} method. The implementations of
* these methods should complete in a timely manner so as to avoid keeping the
* invoking thread from dispatching to other completion handlers.
*
* @param <V> The result type of the I/O operation
* @param <A> The type of the object attached to the I/O operation
*
* @since 1.7
*/
public interface CompletionHandler<V,A> {
/**
* Invoked when an operation has completed.
*
* @param result
* The result of the I/O operation.
* @param attachment
* The object attached to the I/O operation when it was initiated.
*/
void completed(V result, A attachment);
/**
* Invoked when an operation fails.
*
* @param exc
* The exception to indicate why the I/O operation failed
* @param attachment
* The object attached to the I/O operation when it was initiated.
*/
void failed(Throwable exc, A attachment);
/**
* Invoked when an operation is cancelled by invoking the {@link
* java.util.concurrent.Future#cancel cancel} method.
*
* @param attachment
* The object attached to the I/O operation when it was initiated.
*/
void cancelled(A attachment);
}

18
jdk/src/share/classes/java/nio/channels/DatagramChannel.java
View file

@ -1,5 +1,5 @@
/*
* Copyright 2000-2008 Sun Microsystems, Inc. All Rights Reserved.
* Copyright 2000-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -31,7 +31,8 @@ import java.net.DatagramSocket;
import java.net.SocketOption;
import java.net.SocketAddress;
import java.nio.ByteBuffer;
import java.nio.channels.spi.*;
import java.nio.channels.spi.AbstractSelectableChannel;
import java.nio.channels.spi.SelectorProvider;
/**
* A selectable channel for datagram-oriented sockets.
@ -53,7 +54,8 @@ import java.nio.channels.spi.*;
* be determined by invoking its {@link #isConnected isConnected} method.
*
* <p> Socket options are configured using the {@link #setOption(SocketOption,Object)
* setOption} method. Datagram channels support the following options:
* setOption} method. A datagram channel to an Internet Protocol socket supports
* the following options:
* <blockquote>
* <table border>
* <tr>
@ -211,6 +213,7 @@ public abstract class DatagramChannel
throws IOException;
/**
* @throws UnsupportedOperationException {@inheritDoc}
* @throws IllegalArgumentException {@inheritDoc}
* @throws ClosedChannelException {@inheritDoc}
* @throws IOException {@inheritDoc}
@ -220,7 +223,6 @@ public abstract class DatagramChannel
public abstract <T> DatagramChannel setOption(SocketOption<T> name, T value)
throws IOException;
/**
* Retrieves a datagram socket associated with this channel.
*
@ -313,15 +315,17 @@ public abstract class DatagramChannel
/**
* Returns the remote address to which this channel's socket is connected.
*
* @return The remote address; {@code null} if the channel is not {@link
* #isOpen open} or the channel's socket is not connected
* @return The remote address; {@code null} if the channel's socket is not
* connected
*
* @throws ClosedChannelException
* If the channel is closed
* @throws IOException
* If an I/O error occurs
*
* @since 1.7
*/
public abstract SocketAddress getConnectedAddress() throws IOException;
public abstract SocketAddress getRemoteAddress() throws IOException;
/**
* Receives a datagram via this channel.

252
jdk/src/share/classes/java/nio/channels/FileChannel.java
View file

@ -1,5 +1,5 @@
/*
* Copyright 2000-2005 Sun Microsystems, Inc. All Rights Reserved.
* Copyright 2000-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -29,16 +29,23 @@ import java.io.*;
import java.nio.ByteBuffer;
import java.nio.MappedByteBuffer;
import java.nio.channels.spi.AbstractInterruptibleChannel;
import java.nio.file.*;
import java.nio.file.attribute.FileAttribute;
import java.nio.file.spi.*;
import java.util.Set;
import java.util.HashSet;
import java.util.Collections;
/**
* A channel for reading, writing, mapping, and manipulating a file.
*
* <p> A file channel has a current <i>position</i> within its file which can
* be both {@link #position() </code>queried<code>} and {@link #position(long)
* </code>modified<code>}. The file itself contains a variable-length sequence
* <p> {@note revised}
* A file channel is a {@link SeekableByteChannel} that is connected to
* a file. It has a current <i>position</i> within its file which can
* be both {@link #position() <i>queried</i>} and {@link #position(long)
* <i>modified</i>}. The file itself contains a variable-length sequence
* of bytes that can be read and written and whose current {@link #size
* </code><i>size</i><code>} can be queried. The size of the file increases
* <i>size</i>} can be queried. The size of the file increases
* when bytes are written beyond its current size; the size of the file
* decreases when it is {@link #truncate </code><i>truncated</i><code>}. The
* file may also have some associated <i>metadata</i> such as access
@ -50,27 +57,27 @@ import java.nio.channels.spi.AbstractInterruptibleChannel;
*
* <ul>
*
* <li><p> Bytes may be {@link #read(ByteBuffer, long) </code>read<code>} or
* {@link #write(ByteBuffer, long) </code>written<code>} at an absolute
* <li><p> Bytes may be {@link #read(ByteBuffer, long) read} or
* {@link #write(ByteBuffer, long) <i>written</i>} at an absolute
* position in a file in a way that does not affect the channel's current
* position. </p></li>
*
* <li><p> A region of a file may be {@link #map </code>mapped<code>}
* <li><p> A region of a file may be {@link #map <i>mapped</i>}
* directly into memory; for large files this is often much more efficient
* than invoking the usual <tt>read</tt> or <tt>write</tt> methods.
* </p></li>
*
* <li><p> Updates made to a file may be {@link #force </code>forced
* out<code>} to the underlying storage device, ensuring that data are not
* <li><p> Updates made to a file may be {@link #force <i>forced
* out</i>} to the underlying storage device, ensuring that data are not
* lost in the event of a system crash. </p></li>
*
* <li><p> Bytes can be transferred from a file {@link #transferTo </code>to
* some other channel<code>}, and {@link #transferFrom </code>vice
* versa<code>}, in a way that can be optimized by many operating systems
* <li><p> Bytes can be transferred from a file {@link #transferTo <i>to
* some other channel</i>}, and {@link #transferFrom <i>vice
* versa</i>}, in a way that can be optimized by many operating systems
* into a very fast transfer directly to or from the filesystem cache.
* </p></li>
*
* <li><p> A region of a file may be {@link FileLock </code>locked<code>}
* <li><p> A region of a file may be {@link FileLock <i>locked</i>}
* against access by other programs. </p></li>
*
* </ul>
@ -96,25 +103,23 @@ import java.nio.channels.spi.AbstractInterruptibleChannel;
* machine. The exact nature of any such inconsistencies are system-dependent
* and are therefore unspecified.
*
* <p> This class does not define methods for opening existing files or for
* creating new ones; such methods may be added in a future release. In this
* release a file channel can be obtained from an existing {@link
* java.io.FileInputStream#getChannel FileInputStream}, {@link
* <p> A file channel is created by invoking one of the {@link #open open}
* methods defined by this class. A file channel can also be obtained from an
* existing {@link java.io.FileInputStream#getChannel FileInputStream}, {@link
* java.io.FileOutputStream#getChannel FileOutputStream}, or {@link
* java.io.RandomAccessFile#getChannel RandomAccessFile} object by invoking
* that object's <tt>getChannel</tt> method, which returns a file channel that
* is connected to the same underlying file.
* is connected to the same underlying file. Where the file channel is obtained
* from an existing stream or random access file then the state of the file
* channel is intimately connected to that of the object whose <tt>getChannel</tt>
* method returned the channel. Changing the channel's position, whether
* explicitly or by reading or writing bytes, will change the file position of
* the originating object, and vice versa. Changing the file's length via the
* file channel will change the length seen via the originating object, and vice
* versa. Changing the file's content by writing bytes will change the content
* seen by the originating object, and vice versa.
*
* <p> The state of a file channel is intimately connected to that of the
* object whose <tt>getChannel</tt> method returned the channel. Changing the
* channel's position, whether explicitly or by reading or writing bytes, will
* change the file position of the originating object, and vice versa.
* Changing the file's length via the file channel will change the length seen
* via the originating object, and vice versa. Changing the file's content by
* writing bytes will change the content seen by the originating object, and
* vice versa.
*
* <a name="open-mode"><p> At various points this class specifies that an
* <a name="open-mode"></a> <p> At various points this class specifies that an
* instance that is "open for reading," "open for writing," or "open for
* reading and writing" is required. A channel obtained via the {@link
* java.io.FileInputStream#getChannel getChannel} method of a {@link
@ -127,7 +132,7 @@ import java.nio.channels.spi.AbstractInterruptibleChannel;
* was created with mode <tt>"r"</tt> and will be open for reading and writing
* if the instance was created with mode <tt>"rw"</tt>.
*
* <a name="append-mode"><p> A file channel that is open for writing may be in
* <a name="append-mode"></a><p> A file channel that is open for writing may be in
* <i>append mode</i>, for example if it was obtained from a file-output stream
* that was created by invoking the {@link
* java.io.FileOutputStream#FileOutputStream(java.io.File,boolean)
@ -138,7 +143,6 @@ import java.nio.channels.spi.AbstractInterruptibleChannel;
* of the data are done in a single atomic operation is system-dependent and
* therefore unspecified.
*
*
* @see java.io.FileInputStream#getChannel()
* @see java.io.FileOutputStream#getChannel()
* @see java.io.RandomAccessFile#getChannel()
@ -147,18 +151,190 @@ import java.nio.channels.spi.AbstractInterruptibleChannel;
* @author Mike McCloskey
* @author JSR-51 Expert Group
* @since 1.4
* @updated 1.7
*/
public abstract class FileChannel
extends AbstractInterruptibleChannel
implements ByteChannel, GatheringByteChannel, ScatteringByteChannel
implements SeekableByteChannel, GatheringByteChannel, ScatteringByteChannel
{
/**
* Initializes a new instance of this class.
*/
protected FileChannel() { }
/**
* {@note new}
* Opens or creates a file, returning a file channel to access the file.
*
* <p> The {@code options} parameter determines how the file is opened.
* The {@link StandardOpenOption#READ READ} and {@link StandardOpenOption#WRITE
* WRITE} options determine if the file should be opened for reading and/or
* writing. If neither option (or the {@link StandardOpenOption#APPEND APPEND}
* option) is contained in the array then the file is opened for reading.
* By default reading or writing commences at the beginning of the file.
*
* <p> In the addition to {@code READ} and {@code WRITE}, the following
* options may be present:
*
* <table border=1 cellpadding=5 summary="">
* <tr> <th>Option</th> <th>Description</th> </tr>
* <tr>
* <td> {@link StandardOpenOption#APPEND APPEND} </td>
* <td> If this option is present then the file is opened for writing and
* each invocation of the channel's {@code write} method first advances
* the position to the end of the file and then writes the requested
* data. Whether the advancement of the position and the writing of the
* data are done in a single atomic operation is system-dependent and
* therefore unspecified. This option may not be used in conjunction
* with the {@code READ} or {@code TRUNCATE_EXISTING} options. </td>
* </tr>
* <tr>
* <td> {@link StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING} </td>
* <td> If this option is present then the existing file is truncated to
* a size of 0 bytes. This option is ignored when the file is opened only
* for reading. </td>
* </tr>
* <tr>
* <td> {@link StandardOpenOption#CREATE_NEW CREATE_NEW} </td>
* <td> If this option is present then a new file is created, failing if
* the file already exists. When creating a file the check for the
* existence of the file and the creation of the file if it does not exist
* is atomic with respect to other file system operations. This option is
* ignored when the file is opened only for reading. </td>
* </tr>
* <tr>
* <td > {@link StandardOpenOption#CREATE CREATE} </td>
* <td> If this option is present then an existing file is opened if it
* exists, otherwise a new file is created. When creating a file the check
* for the existence of the file and the creation of the file if it does
* not exist is atomic with respect to other file system operations. This
* option is ignored if the {@code CREATE_NEW} option is also present or
* the file is opened only for reading. </td>
* </tr>
* <tr>
* <td > {@link StandardOpenOption#DELETE_ON_CLOSE DELETE_ON_CLOSE} </td>
* <td> When this option is present then the implementation makes a
* <em>best effort</em> attempt to delete the file when closed by the
* the {@link #close close} method. If the {@code close} method is not
* invoked then a <em>best effort</em> attempt is made to delete the file
* when the Java virtual machine terminates. </td>
* </tr>
* <tr>
* <td>{@link StandardOpenOption#SPARSE SPARSE} </td>
* <td> When creating a new file this option is a <em>hint</em> that the
* new file will be sparse. This option is ignored when not creating
* a new file. </td>
* </tr>
* <tr>
* <td> {@link StandardOpenOption#SYNC SYNC} </td>
* <td> Requires that every update to the file's content or metadata be
* written synchronously to the underlying storage device. (see <a
* href="../file/package-summary.html#integrity"> Synchronized I/O file
* integrity</a>). </td>
* <tr>
* <tr>
* <td> {@link StandardOpenOption#DSYNC DSYNC} </td>
* <td> Requires that every update to the file's content be written
* synchronously to the underlying storage device. (see <a
* href="../file/package-summary.html#integrity"> Synchronized I/O file
* integrity</a>). </td>
* </tr>
* </table>
*
* <p> An implementation may also support additional options.
*
* <p> The {@code attrs} parameter is an optional array of file {@link
* FileAttribute file-attributes} to set atomically when creating the file.
*
* <p> The new channel is created by invoking the {@link
* FileSystemProvider#newFileChannel newFileChannel} method on the
* provider that created the {@code Path}.
*
* @param file
* The path of the file to open or create
* @param options
* Options specifying how the file is opened
* @param attrs
* An optional list of file attributes to set atomically when
* creating the file
*
* @return A new file channel
*
* @throws IllegalArgumentException
* If the set contains an invalid combination of options
* @throws UnsupportedOperationException
* If the {@code file} is associated with a provider that does not
* support creating file channels, or an unsupported open option is
* specified, or the array contains an attribute that cannot be set
* atomically when creating the file
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* If a security manager is installed and it denies an
* unspecified permission required by the implementation.
* In the case of the default provider, the {@link
* SecurityManager#checkRead(String)} method is invoked to check
* read access if the file is opened for reading. The {@link
* SecurityManager#checkWrite(String)} method is invoked to check
* write access if the file is opened for writing
*
* @since 1.7
*/
public static FileChannel open(Path file,
Set<? extends OpenOption> options,
FileAttribute<?>... attrs)
throws IOException
{
FileSystemProvider provider = file.getFileSystem().provider();
return provider.newFileChannel(file, options, attrs);
}
private static final FileAttribute<?>[] NO_ATTRIBUTES = new FileAttribute[0];
/**
* {@note new}
* Opens or creates a file, returning a file channel to access the file.
*
* <p> An invocation of this method behaves in exactly the same way as the
* invocation
* <pre>
* fc.{@link #open(Path,Set,FileAttribute[]) open}(file, options, new FileAttribute&lt;?&gt;[0]);
* </pre>
*
* @param file
* The path of the file to open or create
* @param options
* Options specifying how the file is opened
*
* @return A new file channel
*
* @throws IllegalArgumentException
* If the set contains an invalid combination of options
* @throws UnsupportedOperationException
* If the {@code file} is associated with a provider that does not
* support creating file channels, or an unsupported open option is
* specified
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* If a security manager is installed and it denies an
* unspecified permission required by the implementation.
* In the case of the default provider, the {@link
* SecurityManager#checkRead(String)} method is invoked to check
* read access if the file is opened for reading. The {@link
* SecurityManager#checkWrite(String)} method is invoked to check
* write access if the file is opened for writing
*
* @since 1.7
*/
public static FileChannel open(Path file, OpenOption... options)
throws IOException
{
Set<OpenOption> set = new HashSet<OpenOption>(options.length);
Collections.addAll(set, options);
return open(file, set, NO_ATTRIBUTES);
}
// -- Channel operations --
@ -286,7 +462,7 @@ public abstract class FileChannel
public abstract FileChannel position(long newPosition) throws IOException;
/**
* Returns the current size of this channel's file. </p>
* Returns the current size of this channel's file. </p>
*
* @return The current size of this channel's file,
* measured in bytes
@ -359,7 +535,7 @@ public abstract class FileChannel
* <p> This method is only guaranteed to force changes that were made to
* this channel's file via the methods defined in this class. It may or
* may not force changes that were made by modifying the content of a
* {@link MappedByteBuffer </code>mapped byte buffer<code>} obtained by
* {@link MappedByteBuffer <i>mapped byte buffer</i>} obtained by
* invoking the {@link #map map} method. Invoking the {@link
* MappedByteBuffer#force force} method of the mapped byte buffer will
* force changes made to the buffer's content to be written. </p>
@ -678,7 +854,7 @@ public abstract class FileChannel
* reading; for a read/write or private mapping, this channel must have
* been opened for both reading and writing.
*
* <p> The {@link MappedByteBuffer </code>mapped byte buffer<code>}
* <p> The {@link MappedByteBuffer <i>mapped byte buffer</i>}
* returned by this method will have a position of zero and a limit and
* capacity of <tt>size</tt>; its mark will be undefined. The buffer and
* the mapping that it represents will remain valid until the buffer itself
@ -717,6 +893,8 @@ public abstract class FileChannel
* The size of the region to be mapped; must be non-negative and
* no greater than {@link java.lang.Integer#MAX_VALUE}
*
* @return The mapped byte buffer
*
* @throws NonReadableChannelException
* If the <tt>mode</tt> is {@link MapMode#READ_ONLY READ_ONLY} but
* this channel was not opened for reading

77
jdk/src/share/classes/java/nio/channels/FileLock.java
View file

@ -1,5 +1,5 @@
/*
* Copyright 2001 Sun Microsystems, Inc. All Rights Reserved.
* Copyright 2001-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -27,14 +27,16 @@ package java.nio.channels;
import java.io.IOException;
/**
* A token representing a lock on a region of a file.
*
* <p> A file-lock object is created each time a lock is acquired on a file via
* one of the {@link FileChannel#lock(long,long,boolean) lock} or {@link
* FileChannel#tryLock(long,long,boolean) tryLock} methods of the {@link
* FileChannel} class.
* FileChannel#tryLock(long,long,boolean) tryLock} methods of the
* {@link FileChannel} class, or the {@link
* AsynchronousFileChannel#lock(long,long,boolean,Object,CompletionHandler) lock}
* or {@link AsynchronousFileChannel#tryLock(long,long,boolean) tryLock}
* methods of the {@link AsynchronousFileChannel} class.
*
* <p> A file-lock object is initially valid. It remains valid until the lock
* is released by invoking the {@link #release release} method, by closing the
@ -70,8 +72,7 @@ import java.io.IOException;
* <p> File-lock objects are safe for use by multiple concurrent threads.
*
*
* <a name="pdep">
* <h4> Platform dependencies </h4>
* <a name="pdep"><h4> Platform dependencies </h4></a>
*
* <p> This file-locking API is intended to map directly to the native locking
* facility of the underlying operating system. Thus the locks held on a file
@ -93,7 +94,7 @@ import java.io.IOException;
*
* <p> On some systems, acquiring a mandatory lock on a region of a file
* prevents that region from being {@link java.nio.channels.FileChannel#map
* </code>mapped into memory<code>}, and vice versa. Programs that combine
* <i>mapped into memory</i>}, and vice versa. Programs that combine
* locking and mapping should be prepared for this combination to fail.
*
* <p> On some systems, closing a channel releases all locks held by the Java
@ -113,11 +114,12 @@ import java.io.IOException;
* @author Mark Reinhold
* @author JSR-51 Expert Group
* @since 1.4
* @updated 1.7
*/
public abstract class FileLock {
private final FileChannel channel;
private final Channel channel;
private final long position;
private final long size;
private final boolean shared;
@ -159,11 +161,66 @@ public abstract class FileLock {
}
/**
* Returns the file channel upon whose file this lock is held. </p>
* {@note new} Initializes a new instance of this class.
*
* @return The file channel
* @param channel
* The channel upon whose file this lock is held
*
* @param position
* The position within the file at which the locked region starts;
* must be non-negative
*
* @param size
* The size of the locked region; must be non-negative, and the sum
* <tt>position</tt>&nbsp;+&nbsp;<tt>size</tt> must be non-negative
*
* @param shared
* <tt>true</tt> if this lock is shared,
* <tt>false</tt> if it is exclusive
*
* @throws IllegalArgumentException
* If the preconditions on the parameters do not hold
*
* @since 1.7
*/
protected FileLock(AsynchronousFileChannel channel,
long position, long size, boolean shared)
{
if (position < 0)
throw new IllegalArgumentException("Negative position");
if (size < 0)
throw new IllegalArgumentException("Negative size");
if (position + size < 0)
throw new IllegalArgumentException("Negative position + size");
this.channel = channel;
this.position = position;
this.size = size;
this.shared = shared;
}
/**
* {@note revised}
* Returns the file channel upon whose file this lock was acquired.
*
* <p> This method has been superseded by the {@link #acquiredBy acquiredBy}
* method.
*
* @return The file channel, or {@code null} if the file lock was not
* acquired by a file channel.
*/
public final FileChannel channel() {
return (channel instanceof FileChannel) ? (FileChannel)channel : null;
}
/**
* {@note new}
* Returns the channel upon whose file this lock was acquired.
*
* @return The channel upon whose file this lock was acquired.
*
* @since 1.7
*/
public Channel acquiredBy() {
return channel;
}

22
jdk/src/share/classes/java/nio/channels/MembershipKey.java
View file

@ -1,5 +1,5 @@
/*
* Copyright 2007-2008 Sun Microsystems, Inc. All Rights Reserved.
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -28,7 +28,6 @@ package java.nio.channels;
import java.net.InetAddress;
import java.net.NetworkInterface;
import java.io.IOException;
import java.util.List;
/**
* A token representing the membership of an Internet Protocol (IP) multicast
@ -38,7 +37,7 @@ import java.util.List;
* to the group, or it may be <em>source-specific</em>, meaning that it
* represents a membership that receives only datagrams from a specific source
* address. Whether or not a membership key is source-specific may be determined
* by invoking its {@link #getSourceAddress() getSourceAddress} method.
* by invoking its {@link #sourceAddress() sourceAddress} method.
*
* <p> A membership key is valid upon creation and remains valid until the
* membership is dropped by invoking the {@link #drop() drop} method, or
@ -93,11 +92,8 @@ public abstract class MembershipKey {
* If the multicast group membership is already invalid then invoking this
* method has no effect. Once a multicast group membership is invalid,
* it remains invalid forever.
*
* @throws IOException
* If an I/O error occurs
*/
public abstract void drop() throws IOException;
public abstract void drop();
/**
* Block multicast datagrams from the given source address.
@ -140,10 +136,8 @@ public abstract class MembershipKey {
* @throws IllegalStateException
* If the given source address is not currently blocked or the
* membership key is no longer valid
* @throws IOException
* If an I/O error occurs
*/
public abstract MembershipKey unblock(InetAddress source) throws IOException;
public abstract MembershipKey unblock(InetAddress source);
/**
* Returns the channel for which this membership key was created. This
@ -152,7 +146,7 @@ public abstract class MembershipKey {
*
* @return the channel
*/
public abstract MulticastChannel getChannel();
public abstract MulticastChannel channel();
/**
* Returns the multicast group for which this membership key was created.
@ -161,7 +155,7 @@ public abstract class MembershipKey {
*
* @return the multicast group
*/
public abstract InetAddress getGroup();
public abstract InetAddress group();
/**
* Returns the network interface for which this membership key was created.
@ -170,7 +164,7 @@ public abstract class MembershipKey {
*
* @return the network interface
*/
public abstract NetworkInterface getNetworkInterface();
public abstract NetworkInterface networkInterface();
/**
* Returns the source address if this membership key is source-specific,
@ -179,5 +173,5 @@ public abstract class MembershipKey {
* @return The source address if this membership key is source-specific,
* otherwise {@code null}
*/
public abstract InetAddress getSourceAddress();
public abstract InetAddress sourceAddress();
}

27
jdk/src/share/classes/java/nio/channels/MulticastChannel.java
View file

@ -1,5 +1,5 @@
/*
* Copyright 2007-2008 Sun Microsystems, Inc. All Rights Reserved.
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -122,6 +122,22 @@ import java.net.StandardSocketOption; // javadoc
public interface MulticastChannel
extends NetworkChannel
{
/**
* Closes this channel.
*
* <p> If the channel is a member of a multicast group then the membership
* is {@link MembershipKey#drop dropped}. Upon return, the {@link
* MembershipKey membership-key} will be {@link MembershipKey#isValid
* invalid}.
*
* <p> This method otherwise behaves exactly as specified by the {@link
* Channel} interface.
*
* @throws IOException
* If an I/O error occurs
*/
@Override void close() throws IOException;
/**
* Joins a multicast group to begin receiving all datagrams sent to the group,
* returning a membership key.
@ -130,7 +146,7 @@ public interface MulticastChannel
* interface to receive all datagrams then the membership key, representing
* that membership, is returned. Otherwise this channel joins the group and
* the resulting new membership key is returned. The resulting membership key
* is not {@link MembershipKey#getSourceAddress source-specific}.
* is not {@link MembershipKey#sourceAddress source-specific}.
*
* <p> A multicast channel may join several multicast groups, including
* the same group on more than one interface. An implementation may impose a
@ -150,6 +166,8 @@ public interface MulticastChannel
* @throws IllegalStateException
* If the channel already has source-specific membership of the
* group on the interface
* @throws UnsupportedOperationException
* If the channel's socket is not an Internet Protocol socket
* @throws ClosedChannelException
* If this channel is closed
* @throws IOException
@ -170,7 +188,7 @@ public interface MulticastChannel
* interface to receive datagrams from the given source address then the
* membership key, representing that membership, is returned. Otherwise this
* channel joins the group and the resulting new membership key is returned.
* The resulting membership key is {@link MembershipKey#getSourceAddress
* The resulting membership key is {@link MembershipKey#sourceAddress
* source-specific}.
*
* <p> Membership is <em>cumulative</em> and this method may be invoked
@ -196,7 +214,8 @@ public interface MulticastChannel
* If the channel is currently a member of the group on the given
* interface to receive all datagrams
* @throws UnsupportedOperationException
* If the underlying operation system does not support source filtering
* If the channel's socket is not an Internet Protocol socket or
* source filtering is not supported
* @throws ClosedChannelException
* If this channel is closed
* @throws IOException

16
jdk/src/share/classes/java/nio/channels/NetworkChannel.java
View file

@ -1,5 +1,5 @@
/*
* Copyright 2007-2008 Sun Microsystems, Inc. All Rights Reserved.
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -95,9 +95,10 @@ public interface NetworkChannel
* java.net.InetSocketAddress}.
*
* @return The socket address that the socket is bound to, or {@code null}
* if the channel is not {@link #isOpen open} or the channel's socket
* is not bound
* if the channel's socket is not bound
*
* @throws ClosedChannelException
* If the channel is closed
* @throws IOException
* If an I/O error occurs
*/
@ -114,9 +115,10 @@ public interface NetworkChannel
*
* @return This channel
*
* @throws UnsupportedOperationException
* If the socket option is not supported by this channel
* @throws IllegalArgumentException
* If the socket option is not supported by this channel, or
* the value is not a valid value for this socket option
* If the value is not a valid value for this socket option
* @throws ClosedChannelException
* If this channel is closed
* @throws IOException
@ -135,7 +137,7 @@ public interface NetworkChannel
* @return The value of the socket option. A value of {@code null} may be
* a valid value for some socket options.
*
* @throws IllegalArgumentException
* @throws UnsupportedOperationException
* If the socket option is not supported by this channel
* @throws ClosedChannelException
* If this channel is closed
@ -154,5 +156,5 @@ public interface NetworkChannel
*
* @return A set of the socket options supported by this channel
*/
Set<SocketOption<?>> options();
Set<SocketOption<?>> supportedOptions();
}

168
jdk/src/share/classes/java/nio/channels/SeekableByteChannel.java Normal file
View file

@ -0,0 +1,168 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.channels;
import java.nio.ByteBuffer;
import java.io.IOException;
/**
* A byte channel that maintains a current <i>position</i> and allows the
* position to be changed.
*
* <p> A seekable byte channel is connected to an entity, typically a file,
* that contains a variable-length sequence of bytes that can be read and
* written. The current position can be {@link #position() <i>queried</i>} and
* {@link #position(long) <i>modified</i>}. The channel also provides access to
* the current <i>size</i> of the entity to which the channel is connected. The
* size increases when bytes are written beyond its current size; the size
* decreases when it is {@link #truncate <i>truncated</i>}.
*
* <p> The {@link #position(long) position} and {@link #truncate truncate} methods
* which do not otherwise have a value to return are specified to return the
* channel upon which they are invoked. This allows method invocations to be
* chained. Implementations of this interface should specialize the return type
* so that method invocations on the implementation class can be chained.
*
* @since 1.7
* @see java.nio.file.FileRef#newByteChannel
*/
public interface SeekableByteChannel
extends ByteChannel
{
/**
* Reads a sequence of bytes from this channel into the given buffer.
*
* <p> Bytes are read starting at this channel's current position, and
* then the position is updated with the number of bytes actually read.
* Otherwise this method behaves exactly as specified in the {@link
* ReadableByteChannel} interface.
*/
@Override
int read(ByteBuffer dst) throws IOException;
/**
* Writes a sequence of bytes to this channel from the given buffer.
*
* <p> Bytes are written starting at this channel's current position, unless
* the channel is connected to an entity such as a file that is opened with
* the {@link java.nio.file.StandardOpenOption#APPEND APPEND} option, in
* which case the position is first advanced to the end. The entity to which
* the channel is connected is grown, if necessary, to accommodate the
* written bytes, and then the position is updated with the number of bytes
* actually written. Otherwise this method behaves exactly as specified by
* the {@link WritableByteChannel} interface.
*/
@Override
int write(ByteBuffer src) throws IOException;
/**
* Returns this channel's position.
*
* @return This channel's position,
* a non-negative integer counting the number of bytes
* from the beginning of the entity to the current position
*
* @throws ClosedChannelException
* If this channel is closed
* @throws IOException
* If some other I/O error occurs
*/
long position() throws IOException;
/**
* Sets this channel's position.
*
* <p> Setting the position to a value that is greater than the current size
* is legal but does not change the size of the entity. A later attempt to
* read bytes at such a position will immediately return an end-of-file
* indication. A later attempt to write bytes at such a position will cause
* the entity to grow to accommodate the new bytes; the values of any bytes
* between the previous end-of-file and the newly-written bytes are
* unspecified.
*
* <p> Setting the channel's position is not recommended when connected to
* an entity, typically a file, that is opened with the {@link
* java.nio.file.StandardOpenOption#APPEND APPEND} option. When opened for
* append, the position is first advanced to the end before writing.
*
* @param newPosition
* The new position, a non-negative integer counting
* the number of bytes from the beginning of the entity
*
* @return This channel
*
* @throws ClosedChannelException
* If this channel is closed
* @throws IllegalArgumentException
* If the new position is negative
* @throws IOException
* If some other I/O error occurs
*/
SeekableByteChannel position(long newPosition) throws IOException;
/**
* Returns the current size of entity to which this channel is connected.
*
* @return The current size, measured in bytes
*
* @throws ClosedChannelException
* If this channel is closed
* @throws IOException
* If some other I/O error occurs
*/
long size() throws IOException;
/**
* Truncates the entity, to which this channel is connected, to the given
* size.
*
* <p> If the given size is less than the current size then the entity is
* truncated, discarding any bytes beyond the new end. If the given size is
* greater than or equal to the current size then the entity is not modified.
* In either case, if the current position is greater than the given size
* then it is set to that size.
*
* <p> An implementation of this interface may prohibit truncation when
* connected to an entity, typically a file, opened with the {@link
* java.nio.file.StandardOpenOption#APPEND APPEND} option.
*
* @param size
* The new size, a non-negative byte count
*
* @return This channel
*
* @throws NonWritableChannelException
* If this channel was not opened for writing
* @throws ClosedChannelException
* If this channel is closed
* @throws IllegalArgumentException
* If the new size is negative
* @throws IOException
* If some other I/O error occurs
*/
SeekableByteChannel truncate(long size) throws IOException;
}

6
jdk/src/share/classes/java/nio/channels/ServerSocketChannel.java
View file

@ -1,5 +1,5 @@
/*
* Copyright 2000-2008 Sun Microsystems, Inc. All Rights Reserved.
* Copyright 2000-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -29,7 +29,8 @@ import java.io.IOException;
import java.net.ServerSocket;
import java.net.SocketOption;
import java.net.SocketAddress;
import java.nio.channels.spi.*;
import java.nio.channels.spi.AbstractSelectableChannel;
import java.nio.channels.spi.SelectorProvider;
/**
* A selectable channel for stream-oriented listening sockets.
@ -195,6 +196,7 @@ public abstract class ServerSocketChannel
throws IOException;
/**
* @throws UnsupportedOperationException {@inheritDoc}
* @throws IllegalArgumentException {@inheritDoc}
* @throws ClosedChannelException {@inheritDoc}
* @throws IOException {@inheritDoc}

16
jdk/src/share/classes/java/nio/channels/SocketChannel.java
View file

@ -1,5 +1,5 @@
/*
* Copyright 2000-2008 Sun Microsystems, Inc. All Rights Reserved.
* Copyright 2000-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -30,7 +30,8 @@ import java.net.Socket;
import java.net.SocketOption;
import java.net.SocketAddress;
import java.nio.ByteBuffer;
import java.nio.channels.spi.*;
import java.nio.channels.spi.AbstractSelectableChannel;
import java.nio.channels.spi.SelectorProvider;
/**
* A selectable channel for stream-oriented connecting sockets.
@ -212,7 +213,7 @@ public abstract class SocketChannel
/**
* @throws ConnectionPendingException
* If a non-blocking connection operation is already in progress on
* If a non-blocking connect operation is already in progress on
* this channel
* @throws AlreadyBoundException {@inheritDoc}
* @throws UnsupportedAddressTypeException {@inheritDoc}
@ -226,6 +227,7 @@ public abstract class SocketChannel
throws IOException;
/**
* @throws UnsupportedOperationException {@inheritDoc}
* @throws IllegalArgumentException {@inheritDoc}
* @throws ClosedChannelException {@inheritDoc}
* @throws IOException {@inheritDoc}
@ -432,15 +434,17 @@ public abstract class SocketChannel
* socket address then the return value from this method is of type {@link
* java.net.InetSocketAddress}.
*
* @return The remote address; {@code null} if the channel is not {@link
* #isOpen open} or the channel's socket is not connected
* @return The remote address; {@code null} if the channel's socket is not
* connected
*
* @throws ClosedChannelException
* If the channel is closed
* @throws IOException
* If an I/O error occurs
*
* @since 1.7
*/
public abstract SocketAddress getConnectedAddress() throws IOException;
public abstract SocketAddress getRemoteAddress() throws IOException;
// -- ByteChannel operations --

37
jdk/src/share/classes/java/nio/channels/exceptions
View file

@ -1,5 +1,5 @@
#
# Copyright 2000-2008 Sun Microsystems, Inc. All Rights Reserved.
# Copyright 2000-2009 Sun Microsystems, Inc. All Rights Reserved.
# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
#
# This code is free software; you can redistribute it and/or modify it
@ -150,6 +150,21 @@ gen OverlappingFileLockException "
SINCE=1.7
SUPER=java.io.IOException
gen InterruptedByTimeoutException "
* Checked exception received by a thread when a timeout elapses before an
* asynchronous operation completes." \
-4268008601014042947L
SUPER=IllegalArgumentException
gen IllegalChannelGroupException "
* Unchecked exception thrown when an attempt is made to open a channel
* in a group that was not created by the same provider. " \
-2495041211157744253L
SUPER=IllegalStateException
gen AlreadyBoundException "
@ -157,3 +172,23 @@ gen AlreadyBoundException "
* network oriented channel that is already bound." \
6796072983322737592L
gen AcceptPendingException "
* Unchecked exception thrown when an attempt is made to initiate an accept
* operation on a channel and a previous accept operation has not completed." \
2721339977965416421L
gen ReadPendingException "
* Unchecked exception thrown when an attempt is made to read from an
* asynchronous socket channel and a previous read has not completed." \
1986315242191227217L
gen WritePendingException "
* Unchecked exception thrown when an attempt is made to write to an
* asynchronous socket channel and a previous write has not completed." \
7031871839266032276L
gen ShutdownChannelGroupException "
* Unchecked exception thrown when an attempt is made to construct a channel in
* a group that is shutdown or the completion handler for an I/O operation
* cannot be invoked because the channel group is shutdown." \
-3903801676350154157L

64
jdk/src/share/classes/java/nio/channels/package-info.java
View file

@ -1,5 +1,5 @@
/*
* Copyright 2001-2008 Sun Microsystems, Inc. All Rights Reserved.
* Copyright 2001-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -46,6 +46,10 @@
* <td>Can read/write to/from a&nbsp;buffer</td></tr>
* <tr><td valign=top><tt>&nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.SeekableByteChannel}</i></tt></td>
* <td>A {@code ByteChannel} connected to an entity that contains a variable-length sequence of bytes</td></tr>
* <tr><td valign=top><tt>&nbsp;&nbsp;<i>{@link java.nio.channels.AsynchronousChannel}</i></tt></td>
* <td>Supports asynchronous I/O operations.</td></tr>
* <tr><td valign=top><tt>&nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.AsynchronousByteChannel}</i></tt></td>
* <td>Can read and write bytes asynchronously</td></tr>
* <tr><td valign=top><tt>&nbsp;&nbsp;<i>{@link java.nio.channels.NetworkChannel}</i></tt></td>
* <td>A channel to a network socket</td></tr>
* <tr><td valign=top><tt>&nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.MulticastChannel}</i></tt></td>
@ -218,12 +222,70 @@
* directly; custom channel classes should extend the appropriate {@link
* java.nio.channels.SelectableChannel} subclasses defined in this package.
*
* <a name="async"></a>
*
* <blockquote><table cellspacing=1 cellpadding=0 summary="Lists asynchronous channels and their descriptions">
* <tr><th><p align="left">Asynchronous I/O</p></th><th><p align="left">Description</p></th></tr>
* <tr><td valign=top><tt>{@link java.nio.channels.AsynchronousFileChannel}</tt></td>
* <td>An asynchronous channel for reading, writing, and manipulating a file</td></tr>
* <tr><td valign=top><tt>{@link java.nio.channels.AsynchronousSocketChannel}</tt></td>
* <td>An asynchronous channel to a stream-oriented connecting socket</td></tr>
* <tr><td valign=top><tt>{@link java.nio.channels.AsynchronousServerSocketChannel}&nbsp;&nbsp;</tt></td>
* <td>An asynchronous channel to a stream-oriented listening socket</td></tr>
* <tr><td valign=top><tt>{@link java.nio.channels.AsynchronousDatagramChannel}</tt></td>
* <td>An asynchronous channel to a datagram-oriented socket</td></tr>
* <tr><td valign=top><tt>{@link java.nio.channels.CompletionHandler}</tt></td>
* <td>A handler for consuming the result of an asynchronous operation</td></tr>
* <tr><td valign=top><tt>{@link java.nio.channels.AsynchronousChannelGroup}</tt></td>
* <td>A grouping of asynchronous channels for the purpose of resource sharing</td></tr>
* </table></blockquote>
*
* <p> {@link java.nio.channels.AsynchronousChannel Asynchronous channels} are a
* special type of channel capable of asynchronous I/O operations. Asynchronous
* channels are non-blocking and define methods to initiate asynchronous
* operations, returning a {@link java.util.concurrent.Future} representing the
* pending result of each operation. The {@code Future} can be used to poll or
* wait for the result of the operation. Asynchronous I/O operations can also
* specify a {@link java.nio.channels.CompletionHandler} to invoke when the
* operation completes. A completion handler is user provided code that is executed
* to consume the result of I/O operation.
*
* <p> This package defines asynchronous-channel classes that are connected to
* a stream-oriented connecting or listening socket, or a datagram-oriented socket.
* It also defines the {@link java.nio.channels.AsynchronousFileChannel} class
* for asynchronous reading, writing, and manipulating a file. As with the {@link
* java.nio.channels.FileChannel} it supports operations to truncate the file
* to a specific size, force updates to the file to be written to the storage
* device, or acquire locks on the whole file or on a specific region of the file.
* Unlike the {@code FileChannel} it does not define methods for mapping a
* region of the file directly into memory. Where memory mapped I/O is required,
* then a {@code FileChannel} can be used.
*
* <p> Asynchronous channels are bound to an asynchronous channel group for the
* purpose of resource sharing. A group has an associated {@link
* java.util.concurrent.ExecutorService} to which tasks are submitted to handle
* I/O events and dispatch to completion handlers that consume the result of
* asynchronous operations performed on channels in the group. The group can
* optionally be specified when creating the channel or the channel can be bound
* to a <em>default group</em>. Sophisticated users may wish to create their
* own asynchronous channel groups or configure the {@code ExecutorService}
* that will be used for the default group.
*
* <p> As with selectors, the implementatin of asynchronous channels can be
* replaced by "plugging in" an alternative definition or instance of the {@link
* java.nio.channels.spi.AsynchronousChannelProvider} class defined in the
* <tt>{@link java.nio.channels.spi}</tt> package. It is not expected that many
* developers will actually make use of this facility; it is provided primarily
* so that sophisticated users can take advantage of operating-system-specific
* asynchronous I/O mechanisms when very high performance is required.
*
* <hr width="80%">
* <p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor
* or method in any class or interface in this package will cause a {@link
* java.lang.NullPointerException NullPointerException} to be thrown.
*
* @since 1.4
* @updated 1.7
* @author Mark Reinhold
* @author JSR-51 Expert Group
*/

264
jdk/src/share/classes/java/nio/channels/spi/AsynchronousChannelProvider.java Normal file
View file

@ -0,0 +1,264 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.channels.spi;
import java.nio.channels.*;
import java.net.ProtocolFamily;
import java.io.IOException;
import java.util.Iterator;
import java.util.ServiceLoader;
import java.util.ServiceConfigurationError;
import java.util.concurrent.*;
import java.security.AccessController;
import java.security.PrivilegedAction;
/**
* Service-provider class for asynchronous channels.
*
* <p> An asynchronous channel provider is a concrete subclass of this class that
* has a zero-argument constructor and implements the abstract methods specified
* below. A given invocation of the Java virtual machine maintains a single
* system-wide default provider instance, which is returned by the {@link
* #provider() provider} method. The first invocation of that method will locate
* the default provider as specified below.
*
* <p> All of the methods in this class are safe for use by multiple concurrent
* threads. </p>
*
* @since 1.7
*/
public abstract class AsynchronousChannelProvider {
private static Void checkPermission() {
SecurityManager sm = System.getSecurityManager();
if (sm != null)
sm.checkPermission(new RuntimePermission("asynchronousChannelProvider"));
return null;
}
private AsynchronousChannelProvider(Void ignore) { }
/**
* Initializes a new instance of this class.
*
* @throws SecurityException
* If a security manager has been installed and it denies
* {@link RuntimePermission}<tt>("asynchronousChannelProvider")</tt>
*/
protected AsynchronousChannelProvider() {
this(checkPermission());
}
// lazy initialization of default provider
private static class ProviderHolder {
static final AsynchronousChannelProvider provider = load();
private static AsynchronousChannelProvider load() {
return AccessController
.doPrivileged(new PrivilegedAction<AsynchronousChannelProvider>() {
public AsynchronousChannelProvider run() {
AsynchronousChannelProvider p;
p = loadProviderFromProperty();
if (p != null)
return p;
p = loadProviderAsService();
if (p != null)
return p;
return sun.nio.ch.DefaultAsynchronousChannelProvider.create();
}});
}
private static AsynchronousChannelProvider loadProviderFromProperty() {
String cn = System.getProperty("java.nio.channels.spi.AsynchronousChannelProvider");
if (cn == null)
return null;
try {
Class<?> c = Class.forName(cn, true,
ClassLoader.getSystemClassLoader());
return (AsynchronousChannelProvider)c.newInstance();
} catch (ClassNotFoundException x) {
throw new ServiceConfigurationError(null, x);
} catch (IllegalAccessException x) {
throw new ServiceConfigurationError(null, x);
} catch (InstantiationException x) {
throw new ServiceConfigurationError(null, x);
} catch (SecurityException x) {
throw new ServiceConfigurationError(null, x);
}
}
private static AsynchronousChannelProvider loadProviderAsService() {
ServiceLoader<AsynchronousChannelProvider> sl =
ServiceLoader.load(AsynchronousChannelProvider.class,
ClassLoader.getSystemClassLoader());
Iterator<AsynchronousChannelProvider> i = sl.iterator();
for (;;) {
try {
return (i.hasNext()) ? i.next() : null;
} catch (ServiceConfigurationError sce) {
if (sce.getCause() instanceof SecurityException) {
// Ignore the security exception, try the next provider
continue;
}
throw sce;
}
}
}
}
/**
* Returns the system-wide default asynchronous channel provider for this
* invocation of the Java virtual machine.
*
* <p> The first invocation of this method locates the default provider
* object as follows: </p>
*
* <ol>
*
* <li><p> If the system property
* <tt>java.nio.channels.spi.AsynchronousChannelProvider</tt> is defined
* then it is taken to be the fully-qualified name of a concrete provider class.
* The class is loaded and instantiated; if this process fails then an
* unspecified error is thrown. </p></li>
*
* <li><p> If a provider class has been installed in a jar file that is
* visible to the system class loader, and that jar file contains a
* provider-configuration file named
* <tt>java.nio.channels.spi.AsynchronousChannelProvider</tt> in the resource
* directory <tt>META-INF/services</tt>, then the first class name
* specified in that file is taken. The class is loaded and
* instantiated; if this process fails then an unspecified error is
* thrown. </p></li>
*
* <li><p> Finally, if no provider has been specified by any of the above
* means then the system-default provider class is instantiated and the
* result is returned. </p></li>
*
* </ol>
*
* <p> Subsequent invocations of this method return the provider that was
* returned by the first invocation. </p>
*
* @return The system-wide default AsynchronousChannel provider
*/
public static AsynchronousChannelProvider provider() {
return ProviderHolder.provider;
}
/**
* Constructs a new asynchronous channel group with a fixed thread pool.
*
* @param nThreads
* The number of threads in the pool
* @param threadFactory
* The factory to use when creating new threads
*
* @throws IllegalArgumentException
* If {@code nThreads <= 0}
* @throws IOException
* If an I/O error occurs
*
* @see AsynchronousChannelGroup#withFixedThreadPool
*/
public abstract AsynchronousChannelGroup
openAsynchronousChannelGroup(int nThreads, ThreadFactory threadFactory) throws IOException;
/**
* Constructs a new asynchronous channel group with the given thread pool.
*
* @param executor
* The thread pool
* @param initialSize
* A value {@code >=0} or a negative value for implementation
* specific default
*
* @throws IOException
* If an I/O error occurs
*
* @see AsynchronousChannelGroup#withCachedThreadPool
*/
public abstract AsynchronousChannelGroup
openAsynchronousChannelGroup(ExecutorService executor, int initialSize) throws IOException;
/**
* Opens an asynchronous server-socket channel.
*
* @param group
* The group to which the channel is bound, or {@code null} to
* bind to the default group
*
* @return The new channel
*
* @throws IllegalChannelGroupException
* If the provider that created the group differs from this provider
* @throws ShutdownChannelGroupException
* The group is shutdown
* @throws IOException
* If an I/O error occurs
*/
public abstract AsynchronousServerSocketChannel openAsynchronousServerSocketChannel
(AsynchronousChannelGroup group) throws IOException;
/**
* Opens an asynchronous socket channel.
*
* @param group
* The group to which the channel is bound, or {@code null} to
* bind to the default group
*
* @return The new channel
*
* @throws IllegalChannelGroupException
* If the provider that created the group differs from this provider
* @throws ShutdownChannelGroupException
* The group is shutdown
* @throws IOException
* If an I/O error occurs
*/
public abstract AsynchronousSocketChannel openAsynchronousSocketChannel
(AsynchronousChannelGroup group) throws IOException;
/**
* Opens an asynchronous datagram channel.
*
* @param family
* The protocol family, or {@code null} for the default protocol
* family
* @param group
* The group to which the channel is bound, or {@code null} to
* bind to the default group
*
* @return The new channel
*
* @throws IllegalChannelGroupException
* If the provider that created the group differs from this provider
* @throws ShutdownChannelGroupException
* The group is shutdown
* @throws IOException
* If an I/O error occurs
*/
public abstract AsynchronousDatagramChannel openAsynchronousDatagramChannel
(ProtocolFamily family, AsynchronousChannelGroup group) throws IOException;
}

6
jdk/src/share/classes/java/nio/channels/spi/SelectorProvider.java
View file

@ -1,5 +1,5 @@
/*
* Copyright 2000-2008 Sun Microsystems, Inc. All Rights Reserved.
* Copyright 2000-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -89,8 +89,8 @@ public abstract class SelectorProvider {
if (cn == null)
return false;
try {
Class c = Class.forName(cn, true,
ClassLoader.getSystemClassLoader());
Class<?> c = Class.forName(cn, true,
ClassLoader.getSystemClassLoader());
provider = (SelectorProvider)c.newInstance();
return true;
} catch (ClassNotFoundException x) {

6
jdk/src/share/classes/java/nio/channels/spi/package.html
View file

@ -1,5 +1,5 @@
<!--
Copyright 2000-2005 Sun Microsystems, Inc. All Rights Reserved.
Copyright 2000-2009 Sun Microsystems, Inc. All Rights Reserved.
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
This code is free software; you can redistribute it and/or modify it
@ -29,8 +29,8 @@
Service-provider classes for the <tt>{@link java.nio.channels}</tt> package.
<p> Only developers who are defining new selector providers should need to make
direct use of this package. </p>
<p> Only developers who are defining new selector providers or asynchronous
channel providers should need to make direct use of this package. </p>
<p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor
or method in any class or interface in this package will cause a {@link

68
jdk/src/share/classes/java/nio/file/AccessDeniedException.java Normal file
View file

@ -0,0 +1,68 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Checked exception thrown when a file system operation is denied, typically
* due to a file permission or other access check.
*
* <p> This exception is not related to the {@link
* java.security.AccessControlException AccessControlException} or {@link
* SecurityException} thrown by access controllers or security managers when
* access to a file is denied.
*
* @since 1.7
*/
public class AccessDeniedException
extends FileSystemException
{
private static final long serialVersionUID = 4943049599949219617L;
/**
* Constructs an instance of this class.
*
* @param file
* A string identifying the file or {@code null} if not known.
*/
public AccessDeniedException(String file) {
super(file);
}
/**
* Constructs an instance of this class.
*
* @param file
* A string identifying the file or {@code null} if not known.
* @param other
* A string identifying the other file or {@code null} if not known.
* @param reason
* A reason message with additional information or {@code null}
*/
public AccessDeniedException(String file, String other, String reason) {
super(file, other, reason);
}
}

49
jdk/src/share/classes/java/nio/file/AccessMode.java Normal file
View file

@ -0,0 +1,49 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Defines access modes used to test the accessibility of a file.
*
* @since 1.7
*
* @see FileRef#checkAccess
*/
public enum AccessMode {
/**
* Test read access.
*/
READ,
/**
* Test write access.
*/
WRITE,
/**
* Test execute access.
*/
EXECUTE;
}

56
jdk/src/share/classes/java/nio/file/AtomicMoveNotSupportedException.java Normal file
View file

@ -0,0 +1,56 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Checked exception thrown when a file cannot be moved as an atomic file system
* operation.
*
* @since 1.7
*/
public class AtomicMoveNotSupportedException
extends FileSystemException
{
static final long serialVersionUID = 5402760225333135579L;
/**
* Constructs an instance of this class.
*
* @param source
* A string identifying the source file or {@code null} if not known.
* @param target
* A string identifying the target file or {@code null} if not known.
* @param reason
* A reason message with additional information
*/
public AtomicMoveNotSupportedException(String source,
String target,
String reason)
{
super(source, target, reason);
}
}

45
jdk/src/share/classes/java/nio/file/ClosedDirectoryStreamException.java Normal file
View file

@ -0,0 +1,45 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Unchecked exception thrown when an attempt is made to invoke an operation on
* a directory stream that is closed.
*
* @since 1.7
*/
public class ClosedDirectoryStreamException
extends IllegalStateException
{
static final long serialVersionUID = 4228386650900895400L;
/**
* Constructs an instance of this class.
*/
public ClosedDirectoryStreamException() {
}
}

43
jdk/src/share/classes/java/nio/file/ClosedFileSystemException.java Normal file
View file

@ -0,0 +1,43 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Unchecked exception thrown when an attempt is made to invoke an operation on
* a file and the file system is closed.
*/
public class ClosedFileSystemException
extends IllegalStateException
{
static final long serialVersionUID = -8158336077256193488L;
/**
* Constructs an instance of this class.
*/
public ClosedFileSystemException() {
}
}

43
jdk/src/share/classes/java/nio/file/ClosedWatchServiceException.java Normal file
View file

@ -0,0 +1,43 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Unchecked exception thrown when an attempt is made to invoke an operation on
* a watch service that is closed.
*/
public class ClosedWatchServiceException
extends IllegalStateException
{
static final long serialVersionUID = 1853336266231677732L;
/**
* Constructs an instance of this class.
*/
public ClosedWatchServiceException() {
}
}

41
jdk/src/share/classes/java/nio/file/CopyOption.java Normal file
View file

@ -0,0 +1,41 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* An object that configures how to copy or move a file.
*
* <p> Objects of this type may be used with the {@link Path#copyTo copyTo} and
* {@link Path#moveTo moveTo} methods to configure how a file is copied or moved.
*
* <p> The {@link StandardCopyOption} enumeration type defines the
* <i>standard</i> options.
*
* @since 1.7
*/
public interface CopyOption {
}

49
jdk/src/share/classes/java/nio/file/DirectoryNotEmptyException.java Normal file
View file

@ -0,0 +1,49 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Checked exception thrown when a file system operation fails because a
* directory is not empty.
*
* @since 1.7
*/
public class DirectoryNotEmptyException
extends FileSystemException
{
static final long serialVersionUID = 3056667871802779003L;
/**
* Constructs an instance of this class.
*
* @param dir
* A string identifying the directory or {@code null} if not known.
*/
public DirectoryNotEmptyException(String dir) {
super(dir);
}
}

138
jdk/src/share/classes/java/nio/file/DirectoryStream.java Normal file
View file

@ -0,0 +1,138 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
import java.util.Iterator;
import java.io.Closeable;
/**
* An object to iterate over the entries in a directory. A directory stream
* allows for convenient use of the for-each construct:
* <pre>
* Path dir = ...
* DirectoryStream&lt;Path&gt; stream = dir.newDirectoryStream();
* try {
* for (Path entry: stream) {
* ..
* }
* } finally {
* stream.close();
* }
* </pre>
*
* <p><b> A {@code DirectoryStream} is not a general-purpose {@code Iterable}.
* While this interface extends {@code Iterable}, the {@code iterator} method
* may only be invoked once to obtain the iterator; a second, or subsequent,
* call to the {@code iterator} method throws {@code IllegalStateException}. </b>
*
* <p> A {@code DirectoryStream} is opened upon creation and is closed by
* invoking the {@link #close close} method. Closing the directory stream
* releases any resources associated with the stream. The {@link
* Files#withDirectory Files.withDirectory} utility method is useful for cases
* where a task is performed on entries in a directory. This method automatically
* closes the directory stream when iteration is complete (or an error occurs).
* Once a directory stream is closed, all further method invocations on the
* iterator throw {@link java.util.concurrent.ConcurrentModificationException}
* with cause {@link ClosedDirectoryStreamException}.
*
* <p> A directory stream is not required to be <i>asynchronously closeable</i>.
* If a thread is blocked on the directory stream's iterator, reading from the
* directory, and another thread invokes the {@code close} method then it may
* require to block until the read operation is complete.
*
* <p> The {@link Iterator#hasNext() hasNext} and {@link Iterator#next() next}
* methods can encounter an I/O error when iterating over the directory in which
* case {@code ConcurrentModificationException} is thrown with cause
* {@link java.io.IOException}. The {@code hasNext} method is guaranteed to
* read-ahead by at least one element. This means that if the {@code hasNext}
* method returns {@code true} and is followed by a call to the {@code next}
* method then it is guaranteed not to fail with a {@code
* ConcurrentModificationException}.
*
* <p> The elements returned by the iterator are in no specific order. Some file
* systems maintain special links to the directory itself and the directory's
* parent directory. Entries representing these links are not returned by the
* iterator.
*
* <p> The iterator's {@link Iterator#remove() remove} method removes the
* directory entry for the last element returned by the iterator, as if by
* invoking the {@link FileRef#delete delete} method. If an I/O error or
* security exception occurs then {@code ConcurrentModificationException} is
* thrown with the cause.
*
* <p> The iterator is <i>weakly consistent</i>. It is thread safe but does not
* freeze the directory while iterating, so it may (or may not) reflect updates
* to the directory that occur after the {@code DirectoryStream} is created.
*
* @param <T> The type of element returned by the iterator
*
* @since 1.7
*
* @see Path#newDirectoryStream
*/
public interface DirectoryStream<T>
extends Closeable, Iterable<T>
{
/**
* An interface that is implemented by objects that decide if a directory
* entry should be accepted or filtered. A {@code Filter} is passed as the
* parameter to the {@link Path#newDirectoryStream(DirectoryStream.Filter)
* newDirectoryStream} method when opening a directory to iterate over the
* entries in the directory.
*
* <p> The {@link DirectoryStreamFilters} class defines factory methods to
* create filters for a number of common usages and also methods to combine
* filters.
*
* @param <T> The type of the directory entry
*
* @since 1.7
*/
public static interface Filter<T> {
/**
* Decides if the given directory entry should be accepted or filtered.
*
* @param entry
* The directory entry to be tested
*
* @return {@code true} if the directory entry should be accepted
*/
boolean accept(T entry);
}
/**
* Returns the iterator associated with this {@code DirectoryStream}.
*
* @return The iterator associated with this {@code DirectoryStream}
*
* @throws IllegalStateException
* If this directory stream is closed or the iterator has already
* been returned
*/
@Override
Iterator<T> iterator();
}

210
jdk/src/share/classes/java/nio/file/DirectoryStreamFilters.java Normal file
View file

@ -0,0 +1,210 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
import java.io.IOException;
import java.io.IOError;
import sun.nio.fs.MimeType;
/**
* This class consists exclusively of static methods that construct or combine
* filters.
*
* @since 1.7
*/
public final class DirectoryStreamFilters {
private DirectoryStreamFilters() { }
/**
* Constructs a directory stream filter that filters directory entries by
* their <a href="http://www.ietf.org/rfc/rfc2045.txt">MIME</a> content
* type. The directory stream filter's {@link
* java.nio.file.DirectoryStream.Filter#accept accept} method returns {@code
* true} if the content type of the directory entry can be determined by
* invoking the {@link Files#probeContentType probeContentType} method, and
* the content type matches the given content type.
*
* <p> The {@code type} parameter is the value of a Multipurpose Internet
* Mail Extension (MIME) content type as defined by <a
* href="http://www.ietf.org/rfc/rfc2045.txt"><i>RFC&nbsp;2045: Multipurpose
* Internet Mail Extensions (MIME) Part One: Format of Internet Message
* Bodies</i></a>. It is parsable according to the grammar in the RFC. Any
* space characters (<code>'&#92;u0020'</code>) surrounding its components are
* ignored. The {@code type} parameter is parsed into its primary and subtype
* components which are used to match the primary and subtype components of
* each directory entry's content type. Parameters are not allowed. The
* primary type matches if it has value {@code '*'} or is equal to the
* primary type of the directory entry's content type without regard to
* case. The subtype matches if has the value {@code '*'} or is equal to the
* subtype of the directory entry's content type without regard to case. If
* both the primary and subtype match then the filter's {@code accept} method
* returns {@code true}. If the content type of a directory entry cannot be
* determined then the entry is filtered.
*
* <p> The {@code accept} method of the resulting directory stream filter
* throws {@link IOError} if the probing of the content type fails by
* throwing an {@link IOException}. Security exceptions are also propogated
* to the caller of the {@code accept} method.
*
* <p> <b>Usage Example:</b>
* Suppose we require to list only the HTML files in a directory.
* <pre>
* DirectoryStream.Filter&lt;FileRef&gt; filter =
* DirectoryStreamFilters.newContentTypeFilter("text/html");
* </pre>
*
* @param type
* The content type
*
* @return A new directory stream filter
*
* @throws IllegalArgumentException
* If the {@code type} parameter cannot be parsed as a MIME type
* or it has parameters
*/
public static <T extends FileRef> DirectoryStream.Filter<T>
newContentTypeFilter(String type)
{
final MimeType matchType = MimeType.parse(type);
if (matchType.hasParameters())
throw new IllegalArgumentException("Parameters not allowed");
return new DirectoryStream.Filter<T>() {
@Override
public boolean accept(T entry) {
String fileType;
try {
fileType = Files.probeContentType(entry);
} catch (IOException x) {
throw new IOError(x);
}
if (fileType != null) {
return matchType.match(fileType);
}
return false;
}
};
}
/**
* Returns a directory stream filter that {@link DirectoryStream.Filter#accept
* accepts} a directory entry if the entry is accepted by all of the given
* filters.
*
* <p> This method returns a filter that invokes, in iterator order, the
* {@code accept} method of each of the filters. If {@code false} is returned
* by any of the filters then the directory entry is filtered. If the
* directory entry is not filtered then the resulting filter accepts the
* entry. If the iterator returns zero elements then the resulting filter
* accepts all directory entries.
*
* <p> <b>Usage Example:</b>
* <pre>
* List&lt;DirectoryStream.Filter&lt;? super Path&gt;&gt; filters = ...
* DirectoryStream.Filter&lt;Path&gt; filter = DirectoryStreamFilters.allOf(filters);
* </pre>
*
* @param filters
* The sequence of filters
*
* @return The resulting filter
*/
public static <T> DirectoryStream.Filter<T>
allOf(final Iterable<? extends DirectoryStream.Filter<? super T>> filters)
{
if (filters == null)
throw new NullPointerException("'filters' is null");
return new DirectoryStream.Filter<T>() {
@Override
public boolean accept(T entry) {
for (DirectoryStream.Filter<? super T> filter: filters) {
if (!filter.accept(entry))
return false;
}
return true;
}
};
}
/**
* Returns a directory stream filter that {@link DirectoryStream.Filter#accept
* accepts} a directory entry if the entry is accepted by one or more of
* the given filters.
*
* <p> This method returns a filter that invokes, in iteration order, the
* {@code accept} method of each of filter. If {@code true} is returned by
* any of the filters then the directory entry is accepted. If none of the
* filters accepts the directory entry then it is filtered. If the iterator
* returns zero elements then the resulting filter filters all directory
* entries.
*
* @param filters
* The sequence of filters
*
* @return The resulting filter
*/
public static <T> DirectoryStream.Filter<T>
anyOf(final Iterable<? extends DirectoryStream.Filter<? super T>> filters)
{
if (filters == null)
throw new NullPointerException("'filters' is null");
return new DirectoryStream.Filter<T>() {
@Override
public boolean accept(T entry) {
for (DirectoryStream.Filter<? super T> filter: filters) {
if (filter.accept(entry))
return true;
}
return false;
}
};
}
/**
* Returns a directory stream filter that is the <em>complement</em> of the
* given filter. The resulting filter {@link
* java.nio.file.DirectoryStream.Filter#accept accepts} a directory entry
* if filtered by the given filter, and filters any entries that are accepted
* by the given filter.
*
* @param filter
* The given filter
*
* @return The resulting filter that is the complement of the given filter
*/
public static <T> DirectoryStream.Filter<T>
complementOf(final DirectoryStream.Filter<T> filter)
{
if (filter == null)
throw new NullPointerException("'filter' is null");
return new DirectoryStream.Filter<T>() {
@Override
public boolean accept(T entry) {
return !filter.accept(entry);
}
};
}
}

64
jdk/src/share/classes/java/nio/file/FileAction.java Normal file
View file

@ -0,0 +1,64 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
import java.io.IOException;
/**
* An interface that is implemented by objects that operate on a file. An
* implementation of this interface is provided to the {@link Files#withDirectory
* withDirectory} utility method so that the file action is {@link #invoke
* invoked} for all accepted entries in the directory, after which, the directory
* is automatically closed.
*
* <p> <b>Usage Example:</b>
* Suppose we require to perform a task on all class files in a directory:
* <pre>
* Path dir = ...
* Files.withDirectory(dir, "*.class", new FileAction&lt;Path&gt;() {
* public void invoke(Path entry) {
* :
* }
* });
* </pre>
*
* @param <T> The type of file reference
*
* @since 1.7
*/
public interface FileAction<T extends FileRef> {
/**
* Invoked for a file.
*
* @param file
* The file
*
* @throws IOException
* If the block terminates due an uncaught I/O exception
*/
void invoke(T file) throws IOException;
}

63
jdk/src/share/classes/java/nio/file/FileAlreadyExistsException.java Normal file
View file

@ -0,0 +1,63 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Checked exception thrown when an attempt is made to create a file or
* directory and a file of that name already exists.
*
* @since 1.7
*/
public class FileAlreadyExistsException
extends FileSystemException
{
static final long serialVersionUID = 7579540934498831181L;
/**
* Constructs an instance of this class.
*
* @param file
* A string identifying the file or {@code null} if not known.
*/
public FileAlreadyExistsException(String file) {
super(file);
}
/**
* Constructs an instance of this class.
*
* @param file
* A string identifying the file or {@code null} if not known.
* @param other
* A string identifying the other file or {@code null} if not known.
* @param reason
* A reason message with additional information or {@code null}
*/
public FileAlreadyExistsException(String file, String other, String reason) {
super(file, other, reason);
}
}

424
jdk/src/share/classes/java/nio/file/FileRef.java Normal file
View file

@ -0,0 +1,424 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
import java.nio.file.attribute.*;
import java.nio.channels.SeekableByteChannel;
import java.io.IOException;
/**
* A reference to a file.
*
* <p> A {@code FileRef} is an object that locates a file and defines methods to
* access the file. The means by which the file is located depends on the
* implementation. In many cases, a file is located by a {@link Path} but it may
* be located by other means such as a file-system identifier.
*
* <p> This interface defines the following operations:
* <ul>
* <li><p> The {@link #newByteChannel newByteChannel} method
* may be used to open a file and obtain a byte channel for reading or
* writing. </p></li>
* <li><p> The {@link #delete delete} method may be used to delete a file.
* </p></li>
* <li><p> The {@link #checkAccess checkAccess} method may be used to check
* the existence or accessibility of a file. </p></li>
* <li><p> The {@link #isSameFile isSameFile} method may be used to test if
* two file references locate the same file. </p></li>
* <li><p> The {@link #getFileStore getFileStore} method may be used to
* obtain the {@link FileStore} representing the storage where a file is
* located. </p></li>
* </ul>
*
* <p> Access to associated metadata or file attributes requires an appropriate
* {@link FileAttributeView FileAttributeView}. The {@link
* #getFileAttributeView(Class,LinkOption[]) getFileAttributeView(Class,LinkOption[])}
* method may be used to obtain a file attribute view that defines type-safe
* methods to read or update file attributes. The {@link
* #getFileAttributeView(String,LinkOption[]) getFileAttributeView(String,LinkOption[])}
* method may be used to obtain a file attribute view where dynamic access to
* file attributes where required.
*
* <p> A {@code FileRef} is immutable and safe for use by multiple concurrent
* threads.
*
* @since 1.7
*/
public interface FileRef {
/**
* Opens the file referenced by this object, returning a seekable byte
* channel to access the file.
*
* <p> The {@code options} parameter determines how the file is opened.
* The {@link StandardOpenOption#READ READ} and {@link StandardOpenOption#WRITE
* WRITE} options determine if the file should be opened for reading and/or
* writing. If neither option (or the {@link StandardOpenOption#APPEND APPEND}
* option) is contained in the array then the file is opened for reading.
* By default reading or writing commences at the beginning of the file.
*
* <p> In the addition to {@code READ} and {@code WRITE}, the following
* options may be present:
*
* <table border=1 cellpadding=5 summary="">
* <tr> <th>Option</th> <th>Description</th> </tr>
* <tr>
* <td> {@link StandardOpenOption#APPEND APPEND} </td>
* <td> If this option is present then the file is opened for writing and
* each invocation of the channel's {@code write} method first advances
* the position to the end of the file and then writes the requested
* data. Whether the advancement of the position and the writing of the
* data are done in a single atomic operation is system-dependent and
* therefore unspecified. This option may not be used in conjunction
* with the {@code READ} or {@code TRUNCATE_EXISTING} options. </td>
* </tr>
* <tr>
* <td> {@link StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING} </td>
* <td> If this option is present then the existing file is truncated to
* a size of 0 bytes. This option is ignored when the file is opened only
* for reading. </td>
* </tr>
* <tr>
* <td> {@link StandardOpenOption#SYNC SYNC} </td>
* <td> Requires that every update to the file's content or metadata be
* written synchronously to the underlying storage device. (see <a
* href="package-summary.html#integrity"> Synchronized I/O file
* integrity</a>). </td>
* </tr>
* <tr>
* <td> {@link StandardOpenOption#DSYNC DSYNC} </td>
* <td> Requires that every update to the file's content be written
* synchronously to the underlying storage device. (see <a
* href="package-summary.html#integrity"> Synchronized I/O file
* integrity</a>). </td>
* </tr>
* </table>
*
* <p> An implementation of this interface may support additional options
* defined by the {@link StandardOpenOption} enumeration type or other
* implementation specific options.
*
* <p> The {@link java.nio.channels.Channels} utility classes defines methods
* to construct input and output streams where inter-operation with the
* {@link java.io} package is required.
*
* @param options
* Options specifying how the file is opened
*
* @return a new seekable byte channel
*
* @throws IllegalArgumentException
* If an invalid combination of options is specified
* @throws UnsupportedOperationException
* If an unsupported open option is specified
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkRead(String) checkRead}
* method is invoked to check read access to the path if the file is
* opened for reading. The {@link SecurityManager#checkWrite(String)
* checkWrite} method is invoked to check write access to the path
* if the file is opened for writing.
*/
SeekableByteChannel newByteChannel(OpenOption... options)
throws IOException;
/**
* Returns the {@link FileStore} representing the file store where the file
* referenced by this object is stored.
*
* <p> Once a reference to the {@code FileStore} is obtained it is
* implementation specific if operations on the returned {@code FileStore},
* or {@link FileStoreAttributeView} objects obtained from it, continue
* to depend on the existence of the file. In particular the behavior is not
* defined for the case that the file is deleted or moved to a different
* file store.
*
* @return The file store where the file is stored
*
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkRead(String) checkRead}
* method is invoked to check read access to the file, and in
* addition it checks {@link RuntimePermission}<tt>
* ("getFileStoreAttributes")</tt>
*/
FileStore getFileStore() throws IOException;
/**
* Checks the existence and optionally the accessibility of the file
* referenced by this object.
*
* <p> This method checks the existence of a file and that this Java virtual
* machine has appropriate privileges that would allow it access the file
* according to all of access modes specified in the {@code modes} parameter
* as follows:
*
* <table border=1 cellpadding=5 summary="">
* <tr> <th>Value</th> <th>Description</th> </tr>
* <tr>
* <td> {@link AccessMode#READ READ} </td>
* <td> Checks that the file exists and that the Java virtual machine has
* permission to read the file. </td>
* </tr>
* <tr>
* <td> {@link AccessMode#WRITE WRITE} </td>
* <td> Checks that the file exists and that the Java virtual machine has
* permission to write to the file, </td>
* </tr>
* <tr>
* <td> {@link AccessMode#EXECUTE EXECUTE} </td>
* <td> Checks that the file exists and that the Java virtual machine has
* permission to {@link Runtime#exec execute} the file. The semantics
* may differ when checking access to a directory. For example, on UNIX
* systems, checking for {@code EXECUTE} access checks that the Java
* virtual machine has permission to search the directory in order to
* access file or subdirectories. </td>
* </tr>
* </table>
*
* <p> If the {@code modes} parameter is of length zero, then the existence
* of the file is checked.
*
* <p> This method follows symbolic links if the file referenced by this
* object is a symbolic link. Depending on the implementation, this method
* may require to read file permissions, access control lists, or other
* file attributes in order to check the effective access to the file. To
* determine the effective access to a file may require access to several
* attributes and so in some implementations this method may not be atomic
* with respect to other file system operations. Furthermore, as the result
* of this method is immediately outdated, there is no guarantee that a
* subsequence access will succeed (or even that it will access the same
* file). Care should be taken when using this method in security sensitive
* applications.
*
* @param modes
* The access modes to check; may have zero elements
*
* @throws UnsupportedOperationException
* An implementation is required to support checking for
* {@code READ}, {@code WRITE}, and {@code EXECUTE} access. This
* exception is specified to allow for the {@code Access} enum to
* be extended in future releases.
* @throws NoSuchFileException
* If a file does not exist <i>(optional specific exception)</i>
* @throws AccessDeniedException
* The requested access would be denied or the access cannot be
* determined because the Java virtual machine has insufficient
* privileges or other reasons. <i>(optional specific exception)</i>
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkRead(String) checkRead}
* is invoked when checking read access to the file or only the
* existence of the file, the {@link SecurityManager#checkWrite(String)
* checkWrite} is invoked when checking write access to the file,
* and {@link SecurityManager#checkExec(String) checkExec} is invoked
* when checking execute access.
*/
void checkAccess(AccessMode... modes) throws IOException;
/**
* Returns a file attribute view of a given type.
*
* <p> A file attribute view provides a read-only or updatable view of a
* set of file attributes. This method is intended to be used where the file
* attribute view defines type-safe methods to read or update the file
* attributes. The {@code type} parameter is the type of the attribute view
* required and the method returns an instance of that type if supported.
* The {@link BasicFileAttributeView} type supports access to the basic
* attributes of a file. Invoking this method to select a file attribute
* view of that type will always return an instance of that class.
*
* <p> The {@code options} array may be used to indicate how symbolic links
* are handled by the resulting file attribute view for the case that the
* file is a symbolic link. By default, symbolic links are followed. If the
* option {@link LinkOption#NOFOLLOW_LINKS NOFOLLOW_LINKS} is present then
* symbolic links are not followed. This option is ignored by implementations
* that do not support symbolic links.
*
* @param type
* The {@code Class} object corresponding to the file attribute view
* @param options
* Options indicating how symbolic links are handled
*
* @return A file attribute view of the specified type, or {@code null} if
* the attribute view type is not available
*
* @throws UnsupportedOperationException
* If options contains an unsupported option. This exception is
* specified to allow the {@code LinkOption} enum be extended
* in future releases.
*
* @see Attributes#readBasicFileAttributes
*/
<V extends FileAttributeView> V getFileAttributeView(Class<V> type, LinkOption... options);
/**
* Returns a file attribute view of the given name.
*
* <p> A file attribute view provides a read-only or updatable view of a
* set of file attributes. This method is intended to be used where
* <em>dynamic access</em> to the file attributes is required. The {@code
* name} parameter specifies the {@link FileAttributeView#name name} of the
* file attribute view and this method returns an instance of that view if
* supported. The {@link BasicFileAttributeView} type supports access to the
* basic attributes of a file and is name {@code "basic"}. Invoking this
* method to select a file attribute view named {@code "basic"} will always
* return an instance of that class.
*
* <p> The {@code options} array may be used to indicate how symbolic links
* are handled by the resulting file attribute view for the case that the
* file is a symbolic link. By default, symbolic links are followed. If the
* option {@link LinkOption#NOFOLLOW_LINKS NOFOLLOW_LINKS} is present then
* symbolic links are not followed. This option is ignored by implementations
* that do not support symbolic links.
*
* @param name
* The name of the file attribute view
* @param options
* Options indicating how symbolic links are handled
*
* @return A file attribute view of the given name, or {@code null} if
* the attribute view is not available
*
* @throws UnsupportedOperationException
* If options contains an unsupported option. This exception is
* specified to allow the {@code LinkOption} enum be extended
* in future releases.
*/
FileAttributeView getFileAttributeView(String name, LinkOption... options);
/**
* Tests if the file referenced by this object is the same file referenced
* by another object.
*
* <p> If this {@code FileRef} and the given {@code FileRef} are {@link
* #equals(Object) equal} then this method returns {@code true} without checking
* if the file exists. If the {@code FileRef} and the given {@code FileRef}
* are associated with different providers, or the given {@code FileRef} is
* {@code null} then this method returns {@code false}. Otherwise, this method
* checks if both {@code FileRefs} locate the same file, and depending on the
* implementation, may require to open or access both files.
*
* <p> If the file system and files remain static, then this method implements
* an equivalence relation for non-null {@code FileRefs}.
* <ul>
* <li>It is <i>reflexive</i>: for a non-null {@code FileRef} {@code f},
* {@code f.isSameFile(f)} should return {@code true}.
* <li>It is <i>symmetric</i>: for two non-null {@code FileRefs}
* {@code f} and {@code g}, {@code f.isSameFile(g)} will equal
* {@code g.isSameFile(f)}.
* <li>It is <i>transitive</i>: for three {@code FileRefs}
* {@code f}, {@code g}, and {@code h}, if {@code f.isSameFile(g)} returns
* {@code true} and {@code g.isSameFile(h)} returns {@code true}, then
* {@code f.isSameFile(h)} will return return {@code true}.
* </ul>
*
* @param other
* The other file reference
*
* @return {@code true} if, and only if, this object and the given object
* locate the same file
*
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkRead(String) checkRead}
* method is invoked to check read access to both files.
*
* @see java.nio.file.attribute.BasicFileAttributes#fileKey
*/
boolean isSameFile(FileRef other) throws IOException;
/**
* Deletes the file referenced by this object.
*
* <p> An implementation may require to examine the file to determine if the
* file is a directory. Consequently this method may not be atomic with respect
* to other file system operations. If the file is a symbolic-link then the
* link is deleted and not the final target of the link.
*
* <p> If the file is a directory then the directory must be empty. In some
* implementations a directory has entries for special files or links that
* are created when the directory is created. In such implementations a
* directory is considered empty when only the special entries exist.
*
* <p> On some operating systems it may not be possible to remove a file when
* it is open and in use by this Java virtual machine or other programs.
*
* @throws NoSuchFileException
* If the file does not exist <i>(optional specific exception)</i>
* @throws DirectoryNotEmptyException
* If the file is a directory and could not otherwise be deleted
* because the directory is not empty <i>(optional specific
* exception)</i>
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkDelete(String)} method
* is invoked to check delete access to the file
*/
void delete() throws IOException;
/**
* Tests this object for equality with another object.
*
* <p> If the given object is not a {@code FileRef} then this method
* immediately returns {@code false}.
*
* <p> For two file references to be considered equal requires that they
* are both the same type of {@code FileRef} and encapsulate components
* to locate the same file. This method does not access the file system and
* the file may not exist.
*
* <p> This method satisfies the general contract of the {@link
* java.lang.Object#equals(Object) Object.equals} method. </p>
*
* @param ob The object to which this object is to be compared
*
* @return {@code true} if, and only if, the given object is a {@code FileRef}
* that is identical to this {@code FileRef}
*
* @see #isSameFile
*/
boolean equals(Object ob);
/**
* Returns the hash-code value for this object.
*
* <p> This method satisfies the general contract of the
* {@link java.lang.Object#hashCode() Object.hashCode} method.
*/
int hashCode();
}

169
jdk/src/share/classes/java/nio/file/FileStore.java Normal file
View file

@ -0,0 +1,169 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
import java.nio.file.attribute.*;
/**
* Storage for files. A {@code FileStore} represents a storage pool, device,
* partition, volume, concrete file system or other implementation specific means
* of file storage. The {@code FileStore} for where a file is stored is obtained
* by invoking the {@link FileRef#getFileStore getFileStore} method, or all file
* stores can be enumerated by invoking the {@link FileSystem#getFileStores
* getFileStores} method.
*
* <p> In addition to the methods defined by this class, a file store may support
* one or more {@link FileStoreAttributeView FileStoreAttributeView} classes
* that provide a read-only or updatable view of a set of file store attributes.
* File stores associated with the default provider support the {@link
* FileStoreSpaceAttributeView} to read the space related attributes of the
* file store.
*
* @since 1.7
*/
public abstract class FileStore {
/**
* Initializes a new instance of this class.
*/
protected FileStore() {
}
/**
* Returns the name of this file store. The format of the name is highly
* implementation specific. It will typically be the name of the storage
* pool or volume.
*
* <p> The string returned by this method may differ from the string
* returned by the {@link Object#toString() toString} method.
*
* @return The name of this file store
*/
public abstract String name();
/**
* Returns the <em>type</em> of this file store. The format of the string
* returned by this method is highly implementation specific. It may
* indicate, for example, the format used or if the file store is local
* or remote.
*
* @return A string representing the type of this file store
*/
public abstract String type();
/**
* Tells whether this file store is read-only. A file store is read-only if
* it does not support write operations or other changes to files. Any
* attempt to create a file, open an existing file for writing etc. causes
* an {@code IOException} to be thrown.
*
* @return {@code true} if, and only if, this file store is read-only
*/
public abstract boolean isReadOnly();
/**
* Tells whether or not this file store supports the file attributes
* identified by the given file attribute view.
*
* <p> Invoking this method to test if the file store supports {@link
* BasicFileAttributeView} will always return {@code true}. In the case of
* the default provider, this method cannot guarantee to give the correct
* result when the file store is not a local storage device. The reasons for
* this are implementation specific and therefore unspecified.
*
* @param type
* The file attribute view type
*
* @return {@code true} if, and only if, the file attribute view is
* supported
*/
public abstract boolean supportsFileAttributeView(Class<? extends FileAttributeView> type);
/**
* Tells whether or not this file store supports the file attributes
* identified by the given file attribute view.
*
* <p> Invoking this method to test if the file store supports {@link
* BasicFileAttributeView}, identified by the name "{@code basic}" will
* always return {@code true}. In the case of the default provider, this
* method cannot guarantee to give the correct result when the file store is
* not a local storage device. The reasons for this are implementation
* specific and therefore unspecified.
*
* @param name
* The {@link FileAttributeView#name name} of file attribute view
*
* @return {@code true} if, and only if, the file attribute view is
* supported
*/
public abstract boolean supportsFileAttributeView(String name);
/**
* Returns a {@code FileStoreAttributeView} of the given type.
*
* <p> This method is intended to be used where the file store attribute
* view defines type-safe methods to read or update the file store attributes.
* The {@code type} parameter is the type of the attribute view required and
* the method returns an instance of that type if supported.
*
* <p> For {@code FileStore} objects created by the default provider, then
* the file stores support the {@link FileStoreSpaceAttributeView} that
* provides access to space attributes. In that case invoking this method
* with a parameter value of {@code FileStoreSpaceAttributeView.class} will
* always return an instance of that class.
*
* @param type
* The {@code Class} object corresponding to the attribute view
*
* @return A file store attribute view of the specified type or
* {@code null} if the attribute view is not available
*/
public abstract <V extends FileStoreAttributeView> V
getFileStoreAttributeView(Class<V> type);
/**
* Returns a {@code FileStoreAttributeView} of the given name.
*
* <p> This method is intended to be used where <em>dynamic access</em> to
* file store attributes is required. The {@code name} parameter specifies
* the {@link FileAttributeView#name name} of the file store attribute view
* and this method returns an instance of that view if supported.
*
* <p> For {@code FileStore} objects created by the default provider, then
* the file stores support the {@link FileStoreSpaceAttributeView} that
* provides access to space attributes. In that case invoking this method
* with a parameter value of {@code "space"} will always return an instance
* of that class.
*
* @param name
* The name of the attribute view
*
* @return A file store attribute view of the given name, or {@code null}
* if the attribute view is not available
*/
public abstract FileStoreAttributeView getFileStoreAttributeView(String name);
}

453
jdk/src/share/classes/java/nio/file/FileSystem.java Normal file
View file

@ -0,0 +1,453 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
import java.nio.file.attribute.*;
import java.nio.file.spi.FileSystemProvider;
import java.util.Set;
import java.io.Closeable;
import java.io.IOException;
/**
* Provides an interface to a file system and is the factory for objects to
* access files and other objects in the file system.
*
* <p> The default file system, obtained by invoking the {@link FileSystems#getDefault
* FileSystems.getDefault} method, provides access to the file system that is
* accessible to the Java virtual machine. The {@link FileSystems} class defines
* methods to create file systems that provide access to other types of file
* systems.
*
* <p> A file system is the factory for several types of objects:
*
* <ul>
* <li><p> The {@link #getPath getPath} method converts a system dependent
* <em>path string</em>, returning a {@link Path} object that may be used
* to locate and access a file. </p></li>
* <li><p> The {@link #getPathMatcher getPathMatcher} method is used
* to create a {@link PathMatcher} that performs match operations on
* paths. </p></li>
* <li><p> The {@link #getFileStores getFileStores} method returns an iterator
* over the underlying {@link FileStore file-stores}. </p></li>
* <li><p> The {@link #getUserPrincipalLookupService getUserPrincipalLookupService}
* method returns the {@link UserPrincipalLookupService} to lookup users or
* groups by name. </p></li>
* <li><p> The {@link #newWatchService newWatchService} method creates a
* {@link WatchService} that may be used to watch objects for changes and
* events. </p></li>
* </ul>
*
* <p> File systems vary greatly. In some cases the file system is a single
* hierarchy of files with one top-level root directory. In other cases it may
* have several distinct file hierarchies, each with its own top-level root
* directory. The {@link #getRootDirectories getRootDirectories} method may be
* used to iterate over the root directories in the file system. A file system
* is typically composed of one or more underlying {@link FileStore file-stores}
* that provide the storage for the files. Theses file stores can also vary in
* the features they support, and the file attributes or <em>meta-data</em> that
* they associate with files.
*
* <p> A file system is open upon creation and can be closed by invoking its
* {@link #close() close} method. Once closed, any further attempt to access
* objects in the file system cause {@link ClosedFileSystemException} to be
* thrown. File systems created by the default {@link FileSystemProvider provider}
* cannot be closed.
*
* <p> A {@code FileSystem} can provide read-only or read-write access to the
* file system. Whether or not a file system provides read-only access is
* established when the {@code FileSystem} is created and can be tested by invoking
* its {@link #isReadOnly() isReadOnly} method. Attempts to write to file stores
* by means of an object associated with a read-only file system throws {@link
* ReadOnlyFileSystemException}.
*
* <p> File systems are safe for use by multiple concurrent threads. The {@link
* #close close} method may be invoked at any time to close a file system but
* whether a file system is <i>asynchronously closeable</i> is provider specific
* and therefore unspecified. In other words, if a thread is accessing an
* object in a file system, and another thread invokes the {@code close} method
* then it may require to block until the first operation is complete. Closing
* a file system causes all open channels, watch services, and other {@link
* Closeable closeable} objects associated with the file system to be closed.
*
* @since 1.7
*/
public abstract class FileSystem
implements Closeable
{
/**
* Initializes a new instance of this class.
*/
protected FileSystem() {
}
/**
* Returns the provider that created this file system.
*
* @return The provider that created this file system.
*/
public abstract FileSystemProvider provider();
/**
* Closes this file system.
*
* <p> After a file system is closed then all subsequent access to the file
* system, either by methods defined by this class or on objects associated
* with this file system, throw {@link ClosedFileSystemException}. If the
* file system is already closed then invoking this method has no effect.
*
* <p> Closing a file system will close all open {@link
* java.nio.channels.Channel channels}, {@link DirectoryStream directory-streams},
* {@link WatchService watch-service}, and other closeable objects associated
* with this file system. The {@link FileSystems#getDefault default} file
* system cannot be closed.
*
* @throws IOException
* If an I/O error occurs
* @throws UnsupportedOperationException
* Thrown in the case of the default file system
*/
@Override
public abstract void close() throws IOException;
/**
* Tells whether or not this file system is open.
*
* <p> File systems created by the default provider are always open.
*
* @return {@code true} if, and only if, this file system is open
*/
public abstract boolean isOpen();
/**
* Tells whether or not this file system allows only read-only access to
* its file stores.
*
* @return {@code true} if, and only if, this file system provides
* read-only access
*/
public abstract boolean isReadOnly();
/**
* Returns the name separator, represented as a string.
*
* <p> The name separator is used to separate names in a path string. An
* implementation may support multiple name separators in which case this
* method returns an implementation specific <em>default</em> name separator.
* This separator is used when creating path strings by invoking the {@link
* Path#toString() toString()} method.
*
* <p> In the case of the default provider, this method returns the same
* separator as {@link java.io.File#separator}.
*
* @return The name separator
*/
public abstract String getSeparator();
/**
* Returns an object to iterate over the paths of the root directories.
*
* <p> A file system provides access to a file store that may be composed
* of a number of distinct file hierarchies, each with its own top-level
* root directory. Unless denied by the security manager, each element in
* the returned iterator corresponds to the root directory of a distinct
* file hierarchy. The order of the elements is not defined. The file
* hierarchies may change during the lifetime of the Java virtual machine.
* For example, in some implementations, the insertion of removable media
* may result in the creation of a new file hierarchy with its own
* top-level directory.
*
* <p> When a security manager is installed, it is invoked to check access
* to the each root directory. If denied, the root directory is not returned
* by the iterator. In the case of the default provider, the {@link
* SecurityManager#checkRead(String)} method is invoked to check read access
* to each root directory. It is system dependent if the permission checks
* are done when the iterator is obtained or during iteration.
*
* @return An object to iterate over the root directories
*/
public abstract Iterable<Path> getRootDirectories();
/**
* Returns an object to iterate over the underlying file stores.
*
* <p> The elements of the returned iterator are the {@link
* FileStore FileStores} for this file system. The order of the elements is
* not defined and the file stores may change during the lifetime of the
* Java virtual machine. When an I/O error occurs, perhaps because a file
* store is not accessible, then it is not returned by the iterator.
*
* <p> In the case of the default provider, and a security manager is
* installed, the security manager is invoked to check {@link
* RuntimePermission}<tt>("getFileStoreAttributes")</tt>. If denied, then
* no file stores are returned by the iterator. In addition, the security
* manager's {@link SecurityManager#checkRead(String)} method is invoked to
* check read access to the file store's <em>top-most</em> directory. If
* denied, the file store is not returned by the iterator. It is system
* dependent if the permission checks are done when the iterator is obtained
* or during iteration.
*
* <p> <b>Usage Example:</b>
* Suppose we want to print the space usage for all file stores:
* <pre>
* for (FileStore store: FileSystems.getDefault().getFileStores()) {
* FileStoreSpaceAttributes attrs = Attributes.readFileStoreSpaceAttributes(store);
* long total = attrs.totalSpace() / 1024;
* long used = (attrs.totalSpace() - attrs.unallocatedSpace()) / 1024;
* long avail = attrs.usableSpace() / 1024;
* System.out.format("%-20s %12d %12d %12d%n", store, total, used, avail);
* }
* </pre>
*
* @return An object to iterate over the backing file stores
*/
public abstract Iterable<FileStore> getFileStores();
/**
* Returns the set of the {@link FileAttributeView#name names} of the file
* attribute views supported by this {@code FileSystem}.
*
* <p> The {@link BasicFileAttributeView} is required to be supported and
* therefore the set contains at least one element, "basic".
*
* <p> The {@link FileStore#supportsFileAttributeView(String)
* supportsFileAttributeView(String)} method may be used to test if an
* underlying {@link FileStore} supports the file attributes identified by a
* file attribute view.
*
* @return An unmodifiable set of the names of the supported file attribute
* views
*/
public abstract Set<String> supportedFileAttributeViews();
/**
* Converts a path string to a {@code Path}.
*
* <p> The parsing and conversion to a path object is inherently
* implementation dependent. In the simplest case, the path string is rejected,
* and {@link InvalidPathException} thrown, if the path string contains
* characters that cannot be converted to characters that are <em>legal</em>
* to the file store. For example, on UNIX systems, the NUL (&#92;u0000)
* character is not allowed to be present in a path. An implementation may
* choose to reject path strings that contain names that are longer than those
* allowed by any file store, and where an implementation supports a complex
* path syntax, it may choose to reject path strings that are <em>badly
* formed</em>.
*
* <p> In the case of the default provider, path strings are parsed based
* on the definition of paths at the platform or virtual file system level.
* For example, an operating system may not allow specific characters to be
* present in a file name, but a specific underlying file store may impose
* different or additional restrictions on the set of legal
* characters.
*
* <p> This method throws {@link InvalidPathException} when the path string
* cannot be converted to a path. Where possible, and where applicable,
* the exception is created with an {@link InvalidPathException#getIndex
* index} value indicating the first position in the {@code path} parameter
* that caused the path string to be rejected.
*
* <p> Invoking this method with an empty path string throws
* {@code InvalidPathException}.
*
* @param path
* The path string
*
* @return A {@code Path} object
*
* @throws InvalidPathException
* If the path string cannot be converted
*/
public abstract Path getPath(String path);
/**
* Returns a {@code PathMatcher} that performs match operations on the
* {@code String} representation of {@link Path} objects by interpreting a
* given pattern.
*
* The {@code syntaxAndPattern} parameter identifies the syntax and the
* pattern and takes the form:
* <blockquote>
* <i>syntax</i><b>:</b><i>pattern</i>
* </blockquote>
* where {@code ':'} stands for itself.
*
* <p> A {@code FileSystem} implementation supports the "{@code glob}" and
* "{@code regex}" syntaxes, and may support others. The value of the syntax
* component is compared without regard to case.
*
* <p> When the syntax is "{@code glob}" then the {@code String}
* representation of the path is matched using a limited pattern language
* that resembles regular expressions but with a simpler syntax. For example:
*
* <blockquote>
* <table border="0">
* <tr>
* <td>{@code *.java}</td>
* <td>Matches a path that represents a file name ending in {@code .java}</td>
* </tr>
* <tr>
* <td>{@code *.*}</td>
* <td>Matches file names containing a dot</td>
* </tr>
* <tr>
* <tr>
* <td>{@code *.{java,class}}</td>
* <td>Matches file names ending with {@code .java} or {@code .class}</td>
* </tr>
* <tr>
* <td>{@code foo.?}</td>
* <td>Matches file names starting with {@code foo.} and a single
* character extension</td>
* </tr>
* <tr>
* <td><tt>&#47;home&#47;*&#47;*</tt>
* <td>Matches <tt>&#47;home&#47;gus&#47;data</tt> on UNIX platforms</td>
* </tr>
* <tr>
* <td><tt>&#47;home&#47;**</tt>
* <td>Matches <tt>&#47;home&#47;gus</tt> and
* <tt>&#47;home&#47;gus&#47;data</tt> on UNIX platforms</td>
* </tr>
* <tr>
* <td><tt>C:&#92;&#92;*</tt>
* <td>Matches <tt>C:&#92;foo</tt> and <tt>C:&#92;bar</tt> on the Windows
* platform (note that the backslash is escaped; as a string literal in the
* Java Language the pattern would be <tt>"C:&#92;&#92;&#92;&#92*"</tt>) </td>
* </tr>
*
* </table>
* </blockquote>
*
* <p> The following rules are used to interpret glob patterns:
*
* <p> <ul>
* <li><p> The {@code *} character matches zero or more {@link Character
* characters} of a {@link Path#getName(int) name} component without
* crossing directory boundaries. </p></li>
*
* <li><p> The {@code **} characters matches zero or more {@link Character
* characters} crossing directory boundaries. </p></li>
*
* <li><p> The {@code ?} character matches exactly one character of a
* name component.</p></li>
*
* <li><p> The backslash character ({@code \}) is used to escape characters
* that would otherwise be interpreted as special characters. The expression
* {@code \\} matches a single backslash and "\{" matches a left brace
* for example. </p></li>
*
* <li><p> The {@code [ ]} characters are a <i>bracket expression</i> that
* match a single character of a name component out of a set of characters.
* For example, {@code [abc]} matches {@code "a"}, {@code "b"}, or {@code "c"}.
* The hyphen ({@code -}) may be used to specify a range so {@code [a-z]}
* specifies a range that matches from {@code "a"} to {@code "z"} (inclusive).
* These forms can be mixed so [abce-g] matches {@code "a"}, {@code "b"},
* {@code "c"}, {@code "e"}, {@code "f"} or {@code "g"}. If the character
* after the {@code [} is a {@code !} then it is used for negation so {@code
* [!a-c]} matches any character except {@code "a"}, {@code "b"}, or {@code
* "c"}.
* <p> Within a bracket expression the {@code *}, {@code ?} and {@code \}
* characters match themselves. The ({@code -}) character matches itself if
* it is the first character within the brackets, or the first character
* after the {@code !} if negating.</p></li>
*
* <li><p> The {@code { }} characters are a group of subpatterns, where
* the group matches if any subpattern in the group matches. The {@code ","}
* character is used to separate the subpatterns. Groups cannot be nested.
* </p></li>
*
* <li><p> All other characters match themselves in an implementation
* dependent manner. This includes characters representing any {@link
* FileSystem#getSeparator name-separators}. </p></li>
*
* <li><p> The matching of {@link Path#getRoot root} components is highly
* implementation-dependent and is not specified. </p></li>
*
* </ul>
*
* <p> When the syntax is "{@code regex}" then the pattern component is a
* regular expression as defined by the {@link java.util.regex.Pattern}
* class.
*
* <p> For both the glob and regex syntaxes, the matching details, such as
* whether the matching is case sensitive, are implementation-dependent
* and therefore not specified.
*
* @param syntaxAndPattern
* The syntax and pattern
*
* @return A path matcher that may be used to match paths against the pattern
*
* @throws IllegalArgumentException
* If the parameter does not take the form: {@code syntax:pattern}
* @throws java.util.regex.PatternSyntaxException
* If the pattern is invalid
* @throws UnsupportedOperationException
* If the pattern syntax is not known to the implementation
*
* @see Path#newDirectoryStream(String)
*/
public abstract PathMatcher getPathMatcher(String syntaxAndPattern);
/**
* Returns the {@code UserPrincipalLookupService} for this file system
* <i>(optional operation)</i>. The resulting lookup service may be used to
* lookup user or group names.
*
* <p> <b>Usage Example:</b>
* Suppose we want to make "joe" the owner of a file:
* <pre>
* Path file = ...
* UserPrincipal joe = file.getFileSystem().getUserPrincipalLookupService()
* .lookupPrincipalByName("joe");
* Attributes.setOwner(file, joe);
* </pre>
*
* @throws UnsupportedOperationException
* If this {@code FileSystem} does not does have a lookup service
*
* @return The {@code UserPrincipalLookupService} for this file system
*/
public abstract UserPrincipalLookupService getUserPrincipalLookupService();
/**
* Constructs a new {@link WatchService} <i>(optional operation)</i>.
*
* <p> This method constructs a new watch service that may be used to watch
* registered objects for changes and events.
*
* @return a new watch service
*
* @throws UnsupportedOperationException
* If this {@code FileSystem} does not support watching file system
* objects for changes and events. This exception is not thrown
* by {@code FileSystems} created by the default provider.
* @throws IOException
* If an I/O error occurs
*/
public abstract WatchService newWatchService() throws IOException;
}

53
jdk/src/share/classes/java/nio/file/FileSystemAlreadyExistsException.java Normal file
View file

@ -0,0 +1,53 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Runtime exception thrown when an attempt is made to create a file system that
* already exists.
*/
public class FileSystemAlreadyExistsException
extends RuntimeException
{
static final long serialVersionUID = -5438419127181131148L;
/**
* Constructs an instance of this class.
*/
public FileSystemAlreadyExistsException() {
}
/**
* Constructs an instance of this class.
*
* @param msg
* The detail message
*/
public FileSystemAlreadyExistsException(String msg) {
super(msg);
}
}

125
jdk/src/share/classes/java/nio/file/FileSystemException.java Normal file
View file

@ -0,0 +1,125 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
import java.io.IOException;
/**
* Thrown when a file system operation fails on one or two files. This class is
* the general class for file system exceptions.
*
* @since 1.7
*/
public class FileSystemException
extends IOException
{
static final long serialVersionUID = -3055425747967319812L;
private final String file;
private final String other;
/**
* Constructs an instance of this class. This constructor should be used
* when an operation involving one file fails and there isn't any additional
* information to explain the reason.
*
* @param file
* A string identifying the file or {@code null} if not known.
*/
public FileSystemException(String file) {
super((String)null);
this.file = file;
this.other = null;
}
/**
* Constructs an instance of this class. This constructor should be used
* when an operation involving two files fails, or there is additional
* information to explain the reason.
*
* @param file
* A string identifying the file or {@code null} if not known.
* @param other
* A string identifying the other file or {@code null} if there
* isn't another file or if not known
* @param reason
* A reason message with additional information or {@code null}
*/
public FileSystemException(String file, String other, String reason) {
super(reason);
this.file = file;
this.other = other;
}
/**
* Returns the file used to create this exception.
*
* @return The file (can be {@code null})
*/
public String getFile() {
return file;
}
/**
* Returns the other file used to create this exception.
*
* @return The other file (can be {@code null})
*/
public String getOtherFile() {
return other;
}
/**
* Returns the string explaining why the file system operation failed.
*
* @return The string explaining why the file system operation failed
*/
public String getReason() {
return super.getMessage();
}
/**
* Returns the detail message string.
*/
@Override
public String getMessage() {
if (file == null && other == null)
return getReason();
StringBuilder sb = new StringBuilder();
if (file != null)
sb.append(file);
if (other != null) {
sb.append(" -> ");
sb.append(other);
}
if (getReason() != null) {
sb.append(": ");
sb.append(getReason());
}
return sb.toString();
}
}

52
jdk/src/share/classes/java/nio/file/FileSystemNotFoundException.java Normal file
View file

@ -0,0 +1,52 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Runtime exception thrown when a file system cannot be found.
*/
public class FileSystemNotFoundException
extends RuntimeException
{
static final long serialVersionUID = 7999581764446402397L;
/**
* Constructs an instance of this class.
*/
public FileSystemNotFoundException() {
}
/**
* Constructs an instance of this class.
*
* @param msg
* The detail message
*/
public FileSystemNotFoundException(String msg) {
super(msg);
}
}

413
jdk/src/share/classes/java/nio/file/FileSystems.java Normal file
View file

@ -0,0 +1,413 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
import java.nio.file.spi.FileSystemProvider;
import java.net.URI;
import java.io.IOException;
import java.security.AccessController;
import java.security.PrivilegedAction;
import java.util.*;
import java.lang.reflect.Constructor;
/**
* Factory methods for file systems. This class defines the {@link #getDefault
* getDefault} method to get the default file system and factory methods to
* construct other types of file systems.
*
* <p> The first invocation of any of the methods defined by this class causes
* the default {@link FileSystemProvider provider} to be loaded. The default
* provider, identified by the URI scheme "file", creates the {@link FileSystem}
* that provides access to the file systems accessible to the Java virtual
* machine. If the process of loading or initializing the default provider fails
* then an unspecified error is thrown.
*
* <p> The first invocation of the {@link FileSystemProvider#installedProviders
* installedProviders} method, by way of invoking any of the {@code
* newFileSystem} methods defined by this class, locates and loads all
* installed file system providers. Installed providers are loaded using the
* service-provider loading facility defined by the {@link ServiceLoader} class.
* Installed providers are loaded using the system class loader. If the
* system class loader cannot be found then the extension class loader is used;
* if there is no extension class loader then the bootstrap class loader is used.
* Providers are typically installed by placing them in a JAR file on the
* application class path or in the extension directory, the JAR file contains a
* provider-configuration file named {@code java.nio.file.spi.FileSystemProvider}
* in the resource directory {@code META-INF/services}, and the file lists one or
* more fully-qualified names of concrete subclass of {@link FileSystemProvider}
* that have a zero argument constructor.
* The ordering that installed providers are located is implementation specific.
* If a provider is instantiated and its {@link FileSystemProvider#getScheme()
* getScheme} returns the same URI scheme of a provider that was previously
* instantiated then the most recently instantiated duplicate is discarded. URI
* schemes are compared without regard to case. During construction a provider
* may safely access files associated with the default provider but care needs
* to be taken to avoid circular loading of other installed providers. If
* circular loading of installed providers is detected then an unspecified error
* is thrown.
*
* <p> This class also defines factory methods that allow a {@link ClassLoader}
* to be specified when locating a provider. As with installed providers, the
* provider classes are identified by placing the provider configuration file
* in the resource directory {@code META-INF/services}.
*
* <p> If a thread initiates the loading of the installed file system providers
* and another thread invokes a method that also attempts to load the providers
* then the method will block until the loading completes.
*
* @since 1.7
*/
public final class FileSystems {
private FileSystems() {
}
// lazy initialization of default file system
private static class DefaultFileSystemHolder {
static final FileSystem defaultFileSystem = defaultFileSystem();
// returns default file system
private static FileSystem defaultFileSystem() {
// load default provider
FileSystemProvider provider = AccessController
.doPrivileged(new PrivilegedAction<FileSystemProvider>() {
public FileSystemProvider run() {
return getDefaultProvider();
}
});
// return file system
return provider.getFileSystem(URI.create("file:///"));
}
// returns default provider
private static FileSystemProvider getDefaultProvider() {
FileSystemProvider provider = sun.nio.fs.DefaultFileSystemProvider.create();
// if the property java.nio.file.spi.DefaultFileSystemProvider is
// set then its value is the name of the default provider (or a list)
String propValue = System
.getProperty("java.nio.file.spi.DefaultFileSystemProvider");
if (propValue != null) {
for (String cn: propValue.split(",")) {
try {
Class<?> c = Class
.forName(cn, true, ClassLoader.getSystemClassLoader());
Constructor<?> ctor = c
.getDeclaredConstructor(FileSystemProvider.class);
provider = (FileSystemProvider)ctor.newInstance(provider);
// must be "file"
if (!provider.getScheme().equals("file"))
throw new Error("Default provider must use scheme 'file'");
} catch (Exception x) {
throw new Error(x);
}
}
}
return provider;
}
}
/**
* Returns the default {@code FileSystem}. The default file system creates
* objects that provide access to the file systems accessible to the Java
* virtual machine. The <em>working directory</em> of the file system is
* the current user directory, named by the system property {@code user.dir}.
* This allows for interoperability with the {@link java.io.File java.io.File}
* class.
*
* <p> The first invocation of any of the methods defined by this class
* locates the default {@link FileSystemProvider provider} object. Where the
* system property {@code java.nio.file.spi.DefaultFileSystemProvider} is
* not defined then the default provider is a system-default provider that
* is invoked to create the default file system.
*
* <p> If the system property {@code java.nio.file.spi.DefaultFileSystemProvider}
* is defined then it is taken to be a list of one or more fully-qualified
* names of concrete provider classes identified by the URI scheme
* {@code "file"}. Where the property is a list of more than one name then
* the names are separated by a comma. Each class is loaded, using the system
* class loader, and instantiated by invoking a one argument constructor
* whose formal parameter type is {@code FileSystemProvider}. The providers
* are loaded and instantiated in the order they are listed in the property.
* If this process fails or a provider's scheme is not equal to {@code "file"}
* then an unspecified error is thrown. URI schemes are normally compared
* without regard to case but for the default provider, the scheme is
* required to be {@code "file"}. The first provider class is instantiated
* by invoking it with a reference to the system-default provider.
* The second provider class is instantiated by invoking it with a reference
* to the first provider instance. The third provider class is instantiated
* by invoking it with a reference to the second instance, and so on. The
* last provider to be instantiated becomes the default provider; its {@code
* getFileSystem} method is invoked with the URI {@code "file:///"} to create
* the default file system.
*
* <p> Subsequent invocations of this method return the file system that was
* returned by the first invocation.
*
* @return the default file system
*/
public static FileSystem getDefault() {
return DefaultFileSystemHolder.defaultFileSystem;
}
/**
* Returns a reference to an existing {@code FileSystem}.
*
* <p> This method iterates over the {@link FileSystemProvider#installedProviders()
* installed} providers to locate the provider that is identified by the URI
* {@link URI#getScheme scheme} of the given URI. URI schemes are compared
* without regard to case. The exact form of the URI is highly provider
* dependent. If found, the provider's {@link FileSystemProvider#getFileSystem
* getFileSystem} method is invoked to obtain a reference to the {@code
* FileSystem}.
*
* <p> Once a file system created by this provider is {@link FileSystem#close
* closed} it is provider-dependent if this method returns a reference to
* the closed file system or throws {@link FileSystemNotFoundException}.
* If the provider allows a new file system to be created with the same URI
* as a file system it previously created then this method throws the
* exception if invoked after the file system is closed (and before a new
* instance is created by the {@link #newFileSystem newFileSystem} method).
*
* <p> If a security manager is installed then a provider implementation
* may require to check a permission before returning a reference to an
* existing file system. In the case of the {@link FileSystems#getDefault
* default} file system, no permission check is required.
*
* @throws IllegalArgumentException
* If the pre-conditions for the {@code uri} parameter aren't met
* @throws FileSystemNotFoundException
* If the file system, identified by the URI, does not exist
* @throws ProviderNotFoundException
* If a provider supporting the URI scheme is not installed
* @throws SecurityException
* If a security manager is installed and it denies an unspecified
* permission.
*/
public static FileSystem getFileSystem(URI uri) {
String scheme = uri.getScheme();
for (FileSystemProvider provider: FileSystemProvider.installedProviders()) {
if (scheme.equalsIgnoreCase(provider.getScheme())) {
return provider.getFileSystem(uri);
}
}
throw new ProviderNotFoundException("Provider \"" + scheme + "\" not found");
}
/**
* Constructs a new file system that is identified by a {@link URI}
*
* <p> This method iterates over the {@link FileSystemProvider#installedProviders()
* installed} providers to locate the provider that is identified by the URI
* {@link URI#getScheme scheme} of the given URI. URI schemes are compared
* without regard to case. The exact form of the URI is highly provider
* dependent. If found, the provider's {@link FileSystemProvider#newFileSystem(URI,Map)
* newFileSystem(URI,Map)} method is invoked to construct the new file system.
*
* <p> Once a file system is {@link FileSystem#close closed} it is
* provider-dependent if the provider allows a new file system to be created
* with the same URI as a file system it previously created.
*
* <p> <b>Usage Example:</b>
* Suppose there is a provider identified by the scheme {@code "memory"}
* installed:
* <pre>
* Map&lt;String,String&gt; env = new HashMap&lt;String,String&gt;();
* env.put("capacity", "16G");
* env.put("blockSize", "4k");
* FileSystem fs = FileSystems.newFileSystem(URI.create("memory:///?name=logfs"), env);
* </pre>
*
* @param uri
* The URI identifying the file system
* @param env
* A map of provider specific properties to configure the file system;
* may be empty
*
* @return A new file system
*
* @throws IllegalArgumentException
* If the pre-conditions for the {@code uri} parameter aren't met,
* or the {@code env} parameter does not contain properties required
* by the provider, or a property value is invalid
* @throws FileSystemAlreadyExistsException
* If the file system has already been created
* @throws ProviderNotFoundException
* If a provider supporting the URI scheme is not installed
* @throws IOException
* An I/O error occurs creating the file system
* @throws SecurityException
* If a security manager is installed and it denies an unspecified
* permission required by the file system provider implementation
*/
public static FileSystem newFileSystem(URI uri, Map<String,?> env)
throws IOException
{
return newFileSystem(uri, env, null);
}
/**
* Constructs a new file system that is identified by a {@link URI}
*
* <p> This method first attempts to locate an installed provider in exactly
* the same manner as the {@link #newFileSystem(URI,Map) newFileSystem(URI,Map)}
* method. If none of the installed providers support the URI scheme then an
* attempt is made to locate the provider using the given class loader. If a
* provider supporting the URI scheme is located then its {@link
* FileSystemProvider#newFileSystem(URI,Map) newFileSystem(URI,Map)} is
* invoked to construct the new file system.
*
* @param uri
* The URI identifying the file system
* @param env
* A map of provider specific properties to configure the file system;
* may be empty
* @param loader
* The class loader to locate the provider or {@code null} to only
* attempt to locate an installed provider
*
* @return A new file system
*
* @throws IllegalArgumentException
* If the pre-conditions for the {@code uri} parameter aren't met,
* or the {@code env} parameter does not contain properties required
* by the provider, or a property value is invalid
* @throws FileSystemAlreadyExistsException
* If the URI scheme identifies an installed provider and the file
* system has already been created
* @throws ProviderNotFoundException
* If a provider supporting the URI scheme is not found
* @throws ServiceConfigurationError
* When an error occurs while loading a service provider
* @throws IOException
* An I/O error occurs creating the file system
* @throws SecurityException
* If a security manager is installed and it denies an unspecified
* permission required by the file system provider implementation
*/
public static FileSystem newFileSystem(URI uri, Map<String,?> env, ClassLoader loader)
throws IOException
{
String scheme = uri.getScheme();
// check installed providers
for (FileSystemProvider provider: FileSystemProvider.installedProviders()) {
if (scheme.equalsIgnoreCase(provider.getScheme())) {
return provider.newFileSystem(uri, env);
}
}
// if not found, use service-provider loading facility
if (loader != null) {
ServiceLoader<FileSystemProvider> sl = ServiceLoader
.load(FileSystemProvider.class, loader);
for (FileSystemProvider provider: sl) {
if (scheme.equalsIgnoreCase(provider.getScheme())) {
return provider.newFileSystem(uri, env);
}
}
}
throw new ProviderNotFoundException("Provider \"" + scheme + "\" not found");
}
/**
* Constructs a new {@code FileSystem} to access the contents of a file as a
* file system.
*
* <p> This method makes use of specialized providers that create pseudo file
* systems where the contents of one or more files is treated as a file
* system. The {@code file} parameter is a reference to an existing file
* and the {@code env} parameter is a map of provider specific properties to
* configure the file system.
*
* <p> This method iterates over the {@link FileSystemProvider#installedProviders()
* installed} providers. It invokes, in turn, each provider's {@link
* FileSystemProvider#newFileSystem(FileRef,Map) newFileSystem(FileRef,Map)} method.
* If a provider returns a file system then the iteration terminates
* and the file system is returned. If none of the installed providers return
* a {@code FileSystem} then an attempt is made to locate the provider using
* the given class loader. If a provider returns a file system then the lookup
* terminates and the file system is returned.
*
* @param file
* A reference to a file
* @param env
* A map of provider specific properties to configure the file system;
* may be empty
* @param loader
* The class loader to locate the provider or {@code null} to only
* attempt to locate an installed provider
*
* @return A new file system
*
* @throws IllegalArgumentException
* If the {@code env} parameter does not contain properties required
* by the provider, or a property value is invalid
* @throws ProviderNotFoundException
* If a provider supporting this file type cannot be located
* @throws ServiceConfigurationError
* When an error occurs while loading a service provider
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* If a security manager is installed and it denies an unspecified
* permission.
*/
public static FileSystem newFileSystem(FileRef file,
Map<String,?> env,
ClassLoader loader)
throws IOException
{
if (file == null)
throw new NullPointerException();
// check installed providers
for (FileSystemProvider provider: FileSystemProvider.installedProviders()) {
try {
return provider.newFileSystem(file, env);
} catch (UnsupportedOperationException uoe) {
}
}
// if not found, use service-provider loading facility
if (loader != null) {
ServiceLoader<FileSystemProvider> sl = ServiceLoader
.load(FileSystemProvider.class, loader);
for (FileSystemProvider provider: sl) {
try {
return provider.newFileSystem(file, env);
} catch (UnsupportedOperationException uoe) {
}
}
}
throw new ProviderNotFoundException("Provider not found");
}
}

244
jdk/src/share/classes/java/nio/file/FileTreeWalker.java Normal file
View file

@ -0,0 +1,244 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
import java.nio.file.attribute.*;
import java.io.IOException;
import java.util.*;
/**
* Simple file tree walker that works in a similar manner to nftw(3C).
*
* @see Files#walkFileTree
*/
class FileTreeWalker {
private final boolean followLinks;
private final boolean detectCycles;
private final LinkOption[] linkOptions;
private final FileVisitor<? super Path> visitor;
FileTreeWalker(Set<FileVisitOption> options, FileVisitor<? super Path> visitor) {
boolean fl = false;
boolean dc = false;
for (FileVisitOption option: options) {
switch (option) {
case FOLLOW_LINKS : fl = true; break;
case DETECT_CYCLES : dc = true; break;
default:
if (option == null)
throw new NullPointerException("Visit options contains 'null'");
throw new AssertionError("Should not get here");
}
}
this.followLinks = fl;
this.detectCycles = fl | dc;
this.linkOptions = (fl) ? new LinkOption[0] :
new LinkOption[] { LinkOption.NOFOLLOW_LINKS };
this.visitor = visitor;
}
/**
* Walk file tree starting at the given file
*/
void walk(Path start, int maxDepth) {
FileVisitResult result = walk(start,
maxDepth,
new ArrayList<AncestorDirectory>());
if (result == null) {
throw new NullPointerException("Visitor returned 'null'");
}
}
/**
* @param file
* The directory to visit
* @param path
* list of directories that is relative path from starting file
* @param depth
* Depth remaining
* @param ancestors
* use when cycle detection is enabled
*/
private FileVisitResult walk(Path file,
int depth,
List<AncestorDirectory> ancestors)
{
// depth check
if (depth-- < 0)
return FileVisitResult.CONTINUE;
BasicFileAttributes attrs = null;
IOException exc = null;
// attempt to get attributes of file. If fails and we are following
// links then a link target might not exist so get attributes of link
try {
try {
attrs = Attributes.readBasicFileAttributes(file, linkOptions);
} catch (IOException x1) {
if (followLinks) {
try {
attrs = Attributes
.readBasicFileAttributes(file, LinkOption.NOFOLLOW_LINKS);
} catch (IOException x2) {
exc = x2;
}
} else {
exc = x1;
}
}
} catch (SecurityException x) {
return FileVisitResult.CONTINUE;
}
// unable to get attributes of file
if (exc != null) {
return visitor.visitFileFailed(file, exc);
}
// file is not a directory so invoke visitFile method
if (!attrs.isDirectory()) {
return visitor.visitFile(file, attrs);
}
// check for cycles
if (detectCycles) {
Object key = attrs.fileKey();
// if this directory and ancestor has a file key then we compare
// them; otherwise we use less efficient isSameFile test.
for (AncestorDirectory ancestor: ancestors) {
Object ancestorKey = ancestor.fileKey();
if (key != null && ancestorKey != null) {
if (key.equals(ancestorKey)) {
// cycle detected
return visitor.visitFile(file, attrs);
}
} else {
try {
if (file.isSameFile(ancestor.file())) {
// cycle detected
return visitor.visitFile(file, attrs);
}
} catch (IOException x) {
// ignore
} catch (SecurityException x) {
// ignore
}
}
}
ancestors.add(new AncestorDirectory(file, key));
}
// visit directory
try {
DirectoryStream<Path> stream = null;
FileVisitResult result;
// open the directory
try {
stream = file.newDirectoryStream();
} catch (IOException x) {
return visitor.preVisitDirectoryFailed(file, x);
} catch (SecurityException x) {
// ignore, as per spec
return FileVisitResult.CONTINUE;
}
// the exception notified to the postVisitDirectory method
IOException ioe = null;
// invoke preVisitDirectory and then visit each entry
try {
result = visitor.preVisitDirectory(file);
if (result != FileVisitResult.CONTINUE) {
return result;
}
// if an I/O occurs during iteration then a CME is thrown. We
// need to distinguish this from a CME thrown by the visitor.
boolean inAction = false;
try {
for (Path entry: stream) {
inAction = true;
result = walk(entry, depth, ancestors);
inAction = false;
// returning null will cause NPE to be thrown
if (result == null || result == FileVisitResult.TERMINATE)
return result;
// skip remaining siblings in this directory
if (result == FileVisitResult.SKIP_SIBLINGS)
break;
}
} catch (ConcurrentModificationException x) {
// if CME thrown because the iteration failed then remember
// the IOException so that it is notified to postVisitDirectory
if (!inAction) {
// iteration failed
Throwable t = x.getCause();
if (t instanceof IOException)
ioe = (IOException)t;
}
if (ioe == null)
throw x;
}
} finally {
try {
stream.close();
} catch (IOException x) { }
}
// invoke postVisitDirectory last
return visitor.postVisitDirectory(file, ioe);
} finally {
// remove key from trail if doing cycle detection
if (detectCycles) {
ancestors.remove(ancestors.size()-1);
}
}
}
private static class AncestorDirectory {
private final FileRef dir;
private final Object key;
AncestorDirectory(FileRef dir, Object key) {
this.dir = dir;
this.key = key;
}
FileRef file() {
return dir;
}
Object fileKey() {
return key;
}
}
}

45
jdk/src/share/classes/java/nio/file/FileVisitOption.java Normal file
View file

@ -0,0 +1,45 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Defines the file tree traversal options.
*
* @since 1.7
*
* @see Files#walkFileTree
*/
public enum FileVisitOption {
/**
* Follow symbolic links.
*/
FOLLOW_LINKS,
/**
* Detect cycles in the file tree.
*/
DETECT_CYCLES;
}

62
jdk/src/share/classes/java/nio/file/FileVisitResult.java Normal file
View file

@ -0,0 +1,62 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* The result type of a {@link FileVisitor FileVisitor}.
*
* @since 1.7
*
* @see Files#walkFileTree
*/
public enum FileVisitResult {
/**
* Continue. When returned from a {@link FileVisitor#preVisitDirectory
* preVisitDirectory} method then the entries in the directory should also
* be visited.
*/
CONTINUE,
/**
* Terminate.
*/
TERMINATE,
/**
* Continue without visiting the entries in this directory. This result
* is only meaningful when returned from the {@link
* FileVisitor#preVisitDirectory preVisitDirectory} method; otherwise
* this result type is the same as returning {@link #CONTINUE}.
*/
SKIP_SUBTREE,
/**
* Continue without visiting the <em>siblings</em> of this file or directory.
* If returned from the {@link FileVisitor#preVisitDirectory
* preVisitDirectory} method then the entries in the directory are also
* skipped and the {@link FileVisitor#postVisitDirectory postVisitDirectory}
* method is not invoked.
*/
SKIP_SIBLINGS;
}

175
jdk/src/share/classes/java/nio/file/FileVisitor.java Normal file
View file

@ -0,0 +1,175 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
import java.nio.file.attribute.BasicFileAttributes;
import java.io.IOException;
/**
* A visitor of files. An implementation of this interface is provided to the
* {@link Files#walkFileTree walkFileTree} utility method to visit each file
* in a tree.
*
* <p> <b>Usage Examples:</b>
* Suppose we want to delete a file tree. In that case, each directory should
* be deleted after the entries in the directory are deleted.
* <pre>
* Path start = ...
* Files.walkFileTree(start, new SimpleFileVisitor&lt;Path&gt;() {
* &#64;Override
* public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) {
* try {
* file.delete(false);
* } catch (IOException exc) {
* // failed to delete
* }
* return FileVisitResult.CONTINUE;
* }
* &#64;Override
* public FileVisitResult postVisitDirectory(Path dir, IOException e) {
* if (e == null) {
* try {
* dir.delete(false);
* } catch (IOException exc) {
* // failed to delete
* }
* } else {
* // directory iteration failed
* }
* return FileVisitResult.CONTINUE;
* }
* });
* </pre>
* <p> Furthermore, suppose we want to copy a file tree rooted at a source
* directory to a target location. In that case, symbolic links should be
* followed and the target directory should be created before the entries in
* the directory are copied.
* <pre>
* final Path source = ...
* final Path target = ...
*
* Files.walkFileTree(source, EnumSet.of(FileVisitOption.FOLLOW_LINKS), Integer.MAX_VALUE,
* new SimpleFileVisitor&lt;Path&gt;() {
* &#64;Override
* public FileVisitResult preVisitDirectory(Path dir) {
* try {
* dir.copyTo(target.resolve(source.relativize(dir)));
* } catch (FileAlreadyExistsException e) {
* // ignore
* } catch (IOException e) {
* // copy failed, skip rest of directory and descendants
* return SKIP_SUBTREE;
* }
* return CONTINUE;
* }
* &#64;Override
* public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) {
* try {
* file.copyTo(target.resolve(source.relativize(file)));
* } catch (IOException e) {
* // copy failed
* }
* return CONTINUE;
* }
* });
* </pre>
*
* @since 1.7
*/
public interface FileVisitor<T extends FileRef> {
/**
* Invoked for a directory before entries in the directory are visited.
*
* <p> If this method returns {@link FileVisitResult#CONTINUE CONTINUE},
* then entries in the directory are visited. If this method returns {@link
* FileVisitResult#SKIP_SUBTREE SKIP_SUBTREE} or {@link
* FileVisitResult#SKIP_SIBLINGS SKIP_SIBLINGS} then entries in the
* directory (and any descendants) will not be visited.
*
* @param dir
* A reference to the directory
*
* @return the visit result
*/
FileVisitResult preVisitDirectory(T dir);
/**
* Invoked for a directory that could not be opened.
*
* @param dir
* A reference to the directory
* @param exc
* The I/O exception thrown from the attempt to open the directory
*
* @return the visit result
*/
FileVisitResult preVisitDirectoryFailed(T dir, IOException exc);
/**
* Invoked for a file in a directory.
*
* @param file
* A reference to the file
* @param attrs
* The file's basic attributes
*
* @return the visit result
*/
FileVisitResult visitFile(T file, BasicFileAttributes attrs);
/**
* Invoked for a file when its basic file attributes could not be read.
*
* @param file
* A reference to the file
* @param exc
* The I/O exception thrown from the attempt to read the file
* attributes
*
* @return the visit result
*/
FileVisitResult visitFileFailed(T file, IOException exc);
/**
* Invoked for a directory after entries in the directory, and all of their
* descendants, have been visited. This method is also invoked when iteration
* of the directory completes prematurely (by a {@link #visitFile visitFile}
* method returning {@link FileVisitResult#SKIP_SIBLINGS SKIP_SIBLINGS},
* or an I/O error when iterating over the directory).
*
* @param dir
* A reference to the directory
* @param exc
* {@code null} if the iteration of the directory completes without
* an error; otherwise the I/O exception that caused the iteration
* of the directory to complete prematurely
*
* @return the visit result
*/
FileVisitResult postVisitDirectory(T dir, IOException exc);
}

406
jdk/src/share/classes/java/nio/file/Files.java Normal file
View file

@ -0,0 +1,406 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
import java.nio.file.spi.FileTypeDetector;
import java.io.IOException;
import java.util.*;
import java.security.AccessController;
import java.security.PrivilegedAction;
/**
* Utility methods for files and directories.
*
* @since 1.7
*/
public final class Files {
private Files() { }
// lazy loading of default and installed file type detectors
private static class DefaultFileTypeDetectorHolder {
static final FileTypeDetector defaultFileTypeDetector =
sun.nio.fs.DefaultFileTypeDetector.create();
static final List<FileTypeDetector> installeDetectors =
loadInstalledDetectors();
// loads all installed file type detectors
private static List<FileTypeDetector> loadInstalledDetectors() {
return AccessController
.doPrivileged(new PrivilegedAction<List<FileTypeDetector>>() {
@Override public List<FileTypeDetector> run() {
List<FileTypeDetector> list = new ArrayList<FileTypeDetector>();
ServiceLoader<FileTypeDetector> loader = ServiceLoader
.load(FileTypeDetector.class, ClassLoader.getSystemClassLoader());
for (FileTypeDetector detector: loader) {
list.add(detector);
}
return list;
}});
}
}
/**
* Probes the content type of a file.
*
* <p> This method uses the installed {@link FileTypeDetector} implementations
* to probe the given file to determine its content type. Each file type
* detector's {@link FileTypeDetector#probeContentType probeContentType} is
* invoked, in turn, to probe the file type. If the file is recognized then
* the content type is returned. If the file is not recognized by any of the
* installed file type detectors then a system-default file type detector is
* invoked to guess the content type.
*
* <p> A given invocation of the Java virtual machine maintains a system-wide
* list of file type detectors. Installed file type detectors are loaded
* using the service-provider loading facility defined by the {@link ServiceLoader}
* class. Installed file type detectors are loaded using the system class
* loader. If the system class loader cannot be found then the extension class
* loader is used; If the extension class loader cannot be found then the
* bootstrap class loader is used. File type detectors are typically installed
* by placing them in a JAR file on the application class path or in the
* extension directory, the JAR file contains a provider-configuration file
* named {@code java.nio.file.spi.FileTypeDetector} in the resource directory
* {@code META-INF/services}, and the file lists one or more fully-qualified
* names of concrete subclass of {@code FileTypeDetector } that have a zero
* argument constructor. If the process of locating or instantiating the
* installed file type detectors fails then an unspecified error is thrown.
* The ordering that installed providers are located is implementation
* specific.
*
* <p> The return value of this method is the string form of the value of a
* Multipurpose Internet Mail Extension (MIME) content type as
* defined by <a href="http://www.ietf.org/rfc/rfc2045.txt"><i>RFC&nbsp;2045:
* Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet
* Message Bodies</i></a>. The string is guaranteed to be parsable according
* to the grammar in the RFC.
*
* @param file
* The file reference
*
* @return The content type of the file, or {@code null} if the content
* type cannot be determined
*
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* If a security manager is installed and it denies an unspecified
* permission required by a file type detector implementation.
*
* @see DirectoryStreamFilters#newContentTypeFilter
*/
public static String probeContentType(FileRef file)
throws IOException
{
// try installed file type detectors
for (FileTypeDetector detector: DefaultFileTypeDetectorHolder.installeDetectors) {
String result = detector.probeContentType(file);
if (result != null)
return result;
}
// fallback to default
return DefaultFileTypeDetectorHolder.defaultFileTypeDetector
.probeContentType(file);
}
/**
* Invokes a {@link FileAction} for each entry in a directory accepted
* by a given {@link java.nio.file.DirectoryStream.Filter filter}.
*
* <p> This method opens the given directory and invokes the file action's
* {@link FileAction#invoke invoke} method for each entry accepted by the
* filter. When iteration is completed then the directory is closed. If the
* {@link DirectoryStream#close close} method throws an {@code IOException}
* then it is silently ignored.
*
* <p> If the {@code FileAction}'s {@code invoke} method terminates due
* to an uncaught {@link IOException}, {@code Error} or {@code RuntimeException}
* then the exception is propagated by this method after closing the
* directory.
*
* @param dir
* The directory
* @param filter
* The filter
* @param action
* The {@code FileAction} to invoke for each accepted entry
*
* @throws NotDirectoryException
* If the {@code dir} parameter is not a directory <i>(optional
* specific exception)</i>
* @throws IOException
* If an I/O error occurs or the {@code invoke} method terminates
* due to an uncaught {@code IOException}
* @throws SecurityException
* In the case of the default provider, the {@link
* SecurityManager#checkRead(String) checkRead} method is invoked
* to check read access to the directory.
*/
public static void withDirectory(Path dir,
DirectoryStream.Filter<? super Path> filter,
FileAction<? super Path> action)
throws IOException
{
// explicit null check required in case directory is empty
if (action == null)
throw new NullPointerException();
DirectoryStream<Path> stream = dir.newDirectoryStream(filter);
try {
// set to true when invoking the action so as to distinguish a
// CME thrown by the iteration from a CME thrown by the invoke
boolean inAction = false;
try {
for (Path entry: stream) {
inAction = true;
action.invoke(entry);
inAction = false;
}
} catch (ConcurrentModificationException cme) {
if (!inAction) {
Throwable cause = cme.getCause();
if (cause instanceof IOException)
throw (IOException)cause;
}
throw cme;
}
} finally {
try {
stream.close();
} catch (IOException x) { }
}
}
/**
* Invokes a {@link FileAction} for each entry in a directory with a
* file name that matches a given pattern.
*
* <p> This method opens the given directory and invokes the file action's
* {@link FileAction#invoke invoke} method for each entry that matches the
* given pattern. When iteration is completed then the directory is closed.
* If the {@link DirectoryStream#close close} method throws an {@code
* IOException} then it is silently ignored.
*
* <p> If the {@code FileAction}'s {@code invoke} method terminates due
* to an uncaught {@link IOException}, {@code Error} or {@code RuntimeException}
* then the exception is propagated by this method after closing the
* directory.
*
* <p> The globbing pattern language supported by this method is as
* specified by the {@link FileSystem#getPathMatcher getPathMatcher} method.
*
* @param dir
* The directory
* @param glob
* The globbing pattern
* @param action
* The {@code FileAction} to invoke for each entry
*
* @throws NotDirectoryException
* If the {@code dir} parameter is not a directory <i>(optional
* specific exception)</i>
* @throws IOException
* If an I/O error occurs or the {@code invoke} method terminates
* due to an uncaught {@code IOException}
* @throws SecurityException
* In the case of the default provider, the {@link
* SecurityManager#checkRead(String) checkRead} method is invoked
* to check read access to the directory.
*/
public static void withDirectory(Path dir,
String glob,
FileAction<? super Path> action)
throws IOException
{
if (glob == null)
throw new NullPointerException("'glob' is null");
final PathMatcher matcher = dir.getFileSystem().getPathMatcher("glob:" + glob);
DirectoryStream.Filter<Path> filter = new DirectoryStream.Filter<Path>() {
@Override
public boolean accept(Path entry) {
return matcher.matches(entry.getName());
}
};
withDirectory(dir, filter, action);
}
/**
* Invokes a {@link FileAction} for all entries in a directory.
*
* <p> This method works as if invoking it were equivalent to evaluating the
* expression:
* <blockquote><pre>
* withDirectory(dir, "*", action)
* </pre></blockquote>
*
* @param dir
* The directory
* @param action
* The {@code FileAction} to invoke for each entry
*
* @throws NotDirectoryException
* If the {@code dir} parameter is not a directory <i>(optional
* specific exception)</i>
* @throws IOException
* If an I/O error occurs or the {@code invoke} method terminates
* due to an uncaught {@code IOException}
* @throws SecurityException
* In the case of the default provider, the {@link
* SecurityManager#checkRead(String) checkRead} method is invoked
* to check read access to the directory.
*/
public static void withDirectory(Path dir, FileAction<? super Path> action)
throws IOException
{
withDirectory(dir, "*", action);
}
/**
* Walks a file tree.
*
* <p> This method walks a file tree rooted at a given starting file. The
* file tree traversal is <em>depth-first</em> with the given {@link
* FileVisitor} invoked for each file encountered. File tree traversal
* completes when all accessible files in the tree have been visited, a
* visitor returns a result of {@link FileVisitResult#TERMINATE TERMINATE},
* or the visitor terminates due to an uncaught {@code Error} or {@code
* RuntimeException}.
*
* <p> For each file encountered this method attempts to gets its {@link
* java.nio.file.attribute.BasicFileAttributes}. If the file is not a
* directory then the {@link FileVisitor#visitFile visitFile} method is
* invoked with the file attributes. If the file attributes cannot be read,
* due to an I/O exception, then the {@link FileVisitor#visitFileFailed
* visitFileFailed} method is invoked with the I/O exception.
*
* <p> Where the file is a directory, this method attempts to open it by
* invoking its {@link Path#newDirectoryStream newDirectoryStream} method.
* Where the directory could not be opened, due to an {@code IOException},
* then the {@link FileVisitor#preVisitDirectoryFailed preVisitDirectoryFailed}
* method is invoked with the I/O exception, after which, the file tree walk
* continues, by default, at the next <em>sibling</em> of the directory.
*
* <p> Where the directory is opened successfully, then the entries in the
* directory, and their <em>descendants</em> are visited. When all entries
* have been visited, or an I/O error occurs during iteration of the
* directory, then the directory is closed and the visitor's {@link
* FileVisitor#postVisitDirectory postVisitDirectory} method is invoked.
* The file tree walk then continues, by default, at the next <em>sibling</em>
* of the directory.
*
* <p> By default, symbolic links are not automatically followed by this
* method. If the {@code options} parameter contains the {@link
* FileVisitOption#FOLLOW_LINKS FOLLOW_LINKS} option then symbolic links are
* followed. When following links, and the attributes of the target cannot
* be read, then this method attempts to get the {@code BasicFileAttributes}
* of the link. If they can be read then the {@code visitFile} method is
* invoked with the attributes of the link (otherwise the {@code visitFileFailed}
* method is invoked as specified above).
*
* <p> If the {@code options} parameter contains the {@link
* FileVisitOption#DETECT_CYCLES DETECT_CYCLES} or {@link
* FileVisitOption#FOLLOW_LINKS FOLLOW_LINKS} options then this method keeps
* track of directories visited so that cycles can be detected. A cycle
* arises when there is an entry in a directory that is an ancestor of the
* directory. Cycle detection is done by recording the {@link
* java.nio.file.attribute.BasicFileAttributes#fileKey file-key} of directories,
* or if file keys are not available, by invoking the {@link FileRef#isSameFile
* isSameFile} method to test if a directory is the same file as an
* ancestor. When a cycle is detected the {@link FileVisitor#visitFile
* visitFile} is invoked with the attributes of the directory. The {@link
* java.nio.file.attribute.BasicFileAttributes#isDirectory isDirectory}
* method may be used to test if the file is a directory and that a cycle is
* detected. The {@code preVisitDirectory} and {@code postVisitDirectory}
* methods are not invoked.
*
* <p> The {@code maxDepth} parameter is the maximum number of levels of
* directories to visit. A value of {@code 0} means that only the starting
* file is visited, unless denied by the security manager. A value of
* {@link Integer#MAX_VALUE MAX_VALUE} may be used to indicate that all
* levels should be visited.
*
* <p> If a visitor returns a result of {@code null} then {@code
* NullPointerException} is thrown.
*
* <p> When a security manager is installed and it denies access to a file
* (or directory), then it is ignored and the visitor is not invoked for
* that file (or directory).
*
* @param start
* The starting file
* @param options
* Options to configure the traversal
* @param maxDepth
* The maximum number of directory levels to visit
* @param visitor
* The file visitor to invoke for each file
*
* @throws IllegalArgumentException
* If the {@code maxDepth} parameter is negative
* @throws SecurityException
* If the security manager denies access to the starting file.
* In the case of the default provider, the {@link
* SecurityManager#checkRead(String) checkRead} method is invoked
* to check read access to the directory.
*/
public static void walkFileTree(Path start,
Set<FileVisitOption> options,
int maxDepth,
FileVisitor<? super Path> visitor)
{
if (maxDepth < 0)
throw new IllegalArgumentException("'maxDepth' is negative");
new FileTreeWalker(options, visitor).walk(start, maxDepth);
}
/**
* Walks a file tree.
*
* <p> This method works as if invoking it were equivalent to evaluating the
* expression:
* <blockquote><pre>
* walkFileTree(start, EnumSet.noneOf(FileVisitOption.class), Integer.MAX_VALUE, visitor)
* </pre></blockquote>
*
* @param start
* The starting file
* @param visitor
* The file visitor to invoke for each file
*
* @throws SecurityException
* If the security manager denies access to the starting file.
* In the case of the default provider, the {@link
* SecurityManager#checkRead(String) checkRead} method is invoked
* to check read access to the directory.
*/
public static void walkFileTree(Path start, FileVisitor<? super Path> visitor) {
walkFileTree(start,
EnumSet.noneOf(FileVisitOption.class),
Integer.MAX_VALUE,
visitor);
}
}

130
jdk/src/share/classes/java/nio/file/InvalidPathException.java Normal file
View file

@ -0,0 +1,130 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Unchecked exception thrown when path string cannot be converted into a
* {@link Path} because the path string contains invalid characters, or
* the path string is invalid for other file system specific reasons.
*/
public class InvalidPathException
extends IllegalArgumentException
{
static final long serialVersionUID = 4355821422286746137L;
private String input;
private int index;
/**
* Constructs an instance from the given input string, reason, and error
* index.
*
* @param input The input string
* @param reason A string explaining why the input was rejected
* @param index The index at which the error occurred,
* or <tt>-1</tt> if the index is not known
*
* @throws NullPointerException
* If either the input or reason strings are <tt>null</tt>
*
* @throws IllegalArgumentException
* If the error index is less than <tt>-1</tt>
*/
public InvalidPathException(String input, String reason, int index) {
super(reason);
if ((input == null) || (reason == null))
throw new NullPointerException();
if (index < -1)
throw new IllegalArgumentException();
this.input = input;
this.index = index;
}
/**
* Constructs an instance from the given input string and reason. The
* resulting object will have an error index of <tt>-1</tt>.
*
* @param input The input string
* @param reason A string explaining why the input was rejected
*
* @throws NullPointerException
* If either the input or reason strings are <tt>null</tt>
*/
public InvalidPathException(String input, String reason) {
this(input, reason, -1);
}
/**
* Returns the input string.
*
* @return The input string
*/
public String getInput() {
return input;
}
/**
* Returns a string explaining why the input string was rejected.
*
* @return The reason string
*/
public String getReason() {
return super.getMessage();
}
/**
* Returns an index into the input string of the position at which the
* error occurred, or <tt>-1</tt> if this position is not known.
*
* @return The error index
*/
public int getIndex() {
return index;
}
/**
* Returns a string describing the error. The resulting string
* consists of the reason string followed by a colon character
* (<tt>':'</tt>), a space, and the input string. If the error index is
* defined then the string <tt>" at index "</tt> followed by the index, in
* decimal, is inserted after the reason string and before the colon
* character.
*
* @return A string describing the error
*/
public String getMessage() {
StringBuffer sb = new StringBuffer();
sb.append(getReason());
if (index > -1) {
sb.append(" at index ");
sb.append(index);
}
sb.append(": ");
sb.append(input);
return sb.toString();
}
}

43
jdk/src/share/classes/java/nio/file/LinkOption.java Normal file
View file

@ -0,0 +1,43 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Defines the options as to how symbolic links are handled.
*
* @since 1.7
*/
public enum LinkOption implements OpenOption, CopyOption {
/**
* Do not follow symbolic links.
*
* @see FileRef#getFileAttributeView(Class,LinkOption[])
* @see Path#copyTo
* @see SecureDirectoryStream#newByteChannel
*/
NOFOLLOW_LINKS;
}

107
jdk/src/share/classes/java/nio/file/LinkPermission.java Normal file
View file

@ -0,0 +1,107 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
import java.security.BasicPermission;
/**
* The {@code Permission} class for link creation operations.
*
* <p> The following table provides a summary description of what the permission
* allows, and discusses the risks of granting code the permission.
*
* <table border=1 cellpadding=5
* summary="Table shows permission target name, what the permission allows, and associated risks">
* <tr>
* <th>Permission Target Name</th>
* <th>What the Permission Allows</th>
* <th>Risks of Allowing this Permission</th>
* </tr>
* <tr>
* <td>hard</td>
* <td> Ability to add an existing file to a directory. This is sometimes
* known as creating a link, or hard link. </td>
* <td> Extreme care should be taken when granting this permission. It allows
* linking to any file or directory in the file system thus allowing the
* attacker to access to all files. </td>
* </tr>
* <tr>
* <td>symbolic</td>
* <td> Ability to create symbolic links. </td>
* <td> Extreme care should be taken when granting this permission. It allows
* linking to any file or directory in the file system thus allowing the
* attacker to access to all files. </td>
* </tr>
* </table>
*
* @since 1.7
*
* @see Path#createLink
* @see Path#createSymbolicLink
*/
public final class LinkPermission extends BasicPermission {
static final long serialVersionUID = -1441492453772213220L;
private void checkName(String name) {
if (!name.equals("hard") && !name.equals("symbolic")) {
throw new IllegalArgumentException("name: " + name);
}
}
/**
* Constructs a {@code LinkPermission} with the specified name.
*
* @param name
* The name of the permission. It must be "hard" or "symbolic".
*
* @throws IllegalArgumentException
* If name is empty or invalid.
*/
public LinkPermission(String name) {
super(name);
checkName(name);
}
/**
* Constructs a {@code LinkPermission} with the specified name.
*
* @param name
* The name of the permission; must be "hard" or "symbolic".
* @param actions
* The actions for the permission; must be the empty string or
* {@code null}
*
* @throws IllegalArgumentException
* If name is empty or invalid.
*/
public LinkPermission(String name, String actions) {
super(name);
checkName(name);
if (actions != null && actions.length() > 0) {
throw new IllegalArgumentException("actions: " + actions);
}
}
}

63
jdk/src/share/classes/java/nio/file/NoSuchFileException.java Normal file
View file

@ -0,0 +1,63 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Checked exception thrown when an attempt is made to access a file that does
* not exist.
*
* @since 1.7
*/
public class NoSuchFileException
extends FileSystemException
{
static final long serialVersionUID = -1390291775875351931L;
/**
* Constructs an instance of this class.
*
* @param file
* A string identifying the file or {@code null} if not known.
*/
public NoSuchFileException(String file) {
super(file);
}
/**
* Constructs an instance of this class.
*
* @param file
* A string identifying the file or {@code null} if not known.
* @param other
* A string identifying the other file or {@code null} if not known.
* @param reason
* A reason message with additional information or {@code null}
*/
public NoSuchFileException(String file, String other, String reason) {
super(file, other, reason);
}
}

49
jdk/src/share/classes/java/nio/file/NotDirectoryException.java Normal file
View file

@ -0,0 +1,49 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Checked exception thrown when a file system operation, intended for a
* directory, fails because the file is not a directory.
*
* @since 1.7
*/
public class NotDirectoryException
extends FileSystemException
{
private static final long serialVersionUID = -9011457427178200199L;
/**
* Constructs an instance of this class.
*
* @param file
* A string identifying the file or {@code null} if not known.
*/
public NotDirectoryException(String file) {
super(file);
}
}

63
jdk/src/share/classes/java/nio/file/NotLinkException.java Normal file
View file

@ -0,0 +1,63 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Checked exception thrown when a file system operation fails because a file
* is not a link.
*
* @since 1.7
*/
public class NotLinkException
extends FileSystemException
{
static final long serialVersionUID = -388655596416518021L;
/**
* Constructs an instance of this class.
*
* @param file
* A string identifying the file or {@code null} if not known.
*/
public NotLinkException(String file) {
super(file);
}
/**
* Constructs an instance of this class.
*
* @param file
* A string identifying the file or {@code null} if not known.
* @param other
* A string identifying the other file or {@code null} if not known.
* @param reason
* A reason message with additional information or {@code null}
*/
public NotLinkException(String file, String other, String reason) {
super(file, other, reason);
}
}

45
jdk/src/share/classes/java/nio/file/OpenOption.java Normal file
View file

@ -0,0 +1,45 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* An object that configures how to open or create a file.
*
* <p> Objects of this type are used by methods such as {@link
* Path#newOutputStream(OpenOption[]) newOutputStream}, {@link
* FileRef#newByteChannel newByteChannel}, {@link
* java.nio.channels.FileChannel#open FileChannel.open}, and {@link
* java.nio.channels.AsynchronousFileChannel#open AsynchronousFileChannel.open}
* when opening or creating a file.
*
* <p> The {@link StandardOpenOption} enumeration type defines the
* <i>standard</i> options.
*
* @since 1.7
*/
public interface OpenOption {
}

1612
jdk/src/share/classes/java/nio/file/Path.java Normal file
View file

File diff suppressed because it is too large Load diff

49
jdk/src/share/classes/java/nio/file/PathMatcher.java Normal file
View file

@ -0,0 +1,49 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* An interface that is implemented by objects that perform match operations on
* paths.
*
* @since 1.7
*
* @see FileSystem#getPathMatcher
* @see Path#newDirectoryStream(String)
*/
public interface PathMatcher {
/**
* Tells if given path matches this matcher's pattern.
*
* @param path
* The path to match
*
* @return {@code true} if, and only if, the path matches this
* matcher's pattern
*/
boolean matches(Path path);
}

123
jdk/src/share/classes/java/nio/file/Paths.java Normal file
View file

@ -0,0 +1,123 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
import java.nio.file.spi.FileSystemProvider;
import java.net.URI;
/**
* This class consists exclusively of static methods that return a {@link Path}
* by converting a path string or {@link URI}.
*
* @since 1.7
*/
public class Paths {
private Paths() { }
/**
* Constructs a {@code Path} by converting the given path string.
*
* <p> The {@code Path} is obtained by invoking the {@link FileSystem#getPath
* getPath} method of the {@link FileSystems#getDefault default} {@link
* FileSystem}.
*
* @param path
* The path string to convert
*
* @return The resulting {@code Path}
*
* @throws InvalidPathException
* If the path string cannot be converted to a {@code Path}
*
* @see FileSystem#getPath
*/
public static Path get(String path) {
return FileSystems.getDefault().getPath(path);
}
/**
* Converts the given URI to a {@link Path} object.
*
* <p> This method iterates over the {@link FileSystemProvider#installedProviders()
* installed} providers to locate the provider that is identified by the
* URI {@link URI#getScheme scheme} of the given URI. URI schemes are
* compared without regard to case. If the provider is found then its {@link
* FileSystemProvider#getPath getPath} method is invoked to convert the
* URI.
*
* <p> In the case of the default provider, identified by the URI scheme
* "file", the given URI has a non-empty path component, and undefined query
* and fragment components. Whether the authority component may be present
* is platform specific. The returned {@code Path} is associated with the
* {@link FileSystems#getDefault default} file system.
*
* <p> The default provider provides a similar <em>round-trip</em> guarantee
* to the {@link java.io.File} class. For a given {@code Path} <i>p</i> it
* is guaranteed that
* <blockquote><tt>
* Paths.get(</tt><i>p</i><tt>.{@link Path#toUri() toUri}()).equals(</tt>
* <i>p</i><tt>.{@link Path#toAbsolutePath() toAbsolutePath}())</tt>
* </blockquote>
* so long as the original {@code Path}, the {@code URI}, and the new {@code
* Path} are all created in (possibly different invocations of) the same
* Java virtual machine. Whether other providers make any guarantees is
* provider specific and therefore unspecified.
*
* @param uri
* The URI to convert
*
* @return The resulting {@code Path}
*
* @throws IllegalArgumentException
* If preconditions on the {@code uri} parameter do not hold. The
* format of the URI is provider specific.
* @throws FileSystemNotFoundException
* If the file system identified by the URI does not exist or the
* provider identified by the URI's scheme component is not installed
* @throws SecurityException
* If a security manager is installed and it denies an unspecified
* permission to access the file system
*/
public static Path get(URI uri) {
String scheme = uri.getScheme();
if (scheme == null)
throw new IllegalArgumentException("Missing scheme");
// check for default provider to avoid loading of installed providers
if (scheme.equalsIgnoreCase("file"))
return FileSystems.getDefault().provider().getPath(uri);
// try to find provider
for (FileSystemProvider provider: FileSystemProvider.installedProviders()) {
if (provider.getScheme().equalsIgnoreCase(scheme)) {
return provider.getPath(uri);
}
}
throw new FileSystemNotFoundException("Provider \"" + scheme + "\" not installed");
}
}

53
jdk/src/share/classes/java/nio/file/ProviderMismatchException.java Normal file
View file

@ -0,0 +1,53 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Unchecked exception thrown when an attempt is made to invoke a method on an
* object created by one file system provider with a parameter created by a
* different file system provider.
*/
public class ProviderMismatchException
extends java.lang.IllegalArgumentException
{
static final long serialVersionUID = 4990847485741612530L;
/**
* Constructs an instance of this class.
*/
public ProviderMismatchException() {
}
/**
* Constructs an instance of this class.
*
* @param msg
* The detail message
*/
public ProviderMismatchException(String msg) {
super(msg);
}
}

52
jdk/src/share/classes/java/nio/file/ProviderNotFoundException.java Normal file
View file

@ -0,0 +1,52 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Runtime exception thrown when a provider of the required type cannot be found.
*/
public class ProviderNotFoundException
extends RuntimeException
{
static final long serialVersionUID = -1880012509822920354L;
/**
* Constructs an instance of this class.
*/
public ProviderNotFoundException() {
}
/**
* Constructs an instance of this class.
*
* @param msg
* The detail message
*/
public ProviderNotFoundException(String msg) {
super(msg);
}
}

43
jdk/src/share/classes/java/nio/file/ReadOnlyFileSystemException.java Normal file
View file

@ -0,0 +1,43 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Unchecked exception thrown when an attempt is made to update an object
* associated with a {@link FileSystem#isReadOnly() read-only} {@code FileSystem}.
*/
public class ReadOnlyFileSystemException
extends UnsupportedOperationException
{
static final long serialVersionUID = -6822409595617487197L;
/**
* Constructs an instance of this class.
*/
public ReadOnlyFileSystemException() {
}
}

324
jdk/src/share/classes/java/nio/file/SecureDirectoryStream.java Normal file
View file

@ -0,0 +1,324 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classname" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
import java.nio.file.attribute.*;
import java.nio.channels.SeekableByteChannel;
import java.util.Set;
import java.io.IOException;
/**
* A {@code DirectoryStream} that defines operations on files that are located
* relative to an open directory. A {@code SecureDirectoryStream} is intended
* for use by sophisticated or security sensitive applications requiring to
* traverse file trees or otherwise operate on directories in a race-free manner.
* Race conditions can arise when a sequence of file operations cannot be
* carried out in isolation. Each of the file operations defined by this
* interface specify a relative {@link Path}. All access to the file is relative
* to the open directory irrespective of if the directory is moved or replaced
* by an attacker while the directory is open. A {@code SecureDirectoryStream}
* may also be used as a virtual <em>working directory</em>.
*
* <p> A {@code SecureDirectoryStream} requires corresponding support from the
* underlying operating system. Where an implementation supports this features
* then the {@code DirectoryStream} returned by the {@link Path#newDirectoryStream
* newDirectoryStream} method will be a {@code SecureDirectoryStream} and must
* be cast to that type in order to invoke the methods defined by this interface.
*
* <p> As specified by {@code DirectoryStream}, the iterator's {@link
* java.util.Iterator#remove() remove} method removes the directory entry for
* the last element returned by the iterator. In the case of a {@code
* SecureDirectoryStream} the {@code remove} method behaves as if by invoking
* the {@link #deleteFile deleteFile} or {@link #deleteDirectory deleteDirectory}
* methods defined by this interface. The {@code remove} may require to examine
* the file to determine if the file is a directory, and consequently, it may
* not be atomic with respect to other file system operations.
*
* <p> In the case of the default {@link java.nio.file.spi.FileSystemProvider
* provider}, and a security manager is set, then the permission checks are
* performed using the path obtained by resolving the given relative path
* against the <i>original path</i> of the directory (irrespective of if the
* directory is moved since it was opened).
*
* @since 1.7
*/
public abstract class SecureDirectoryStream
implements DirectoryStream<Path>
{
/**
* Initialize a new instance of this class.
*/
protected SecureDirectoryStream() { }
/**
* Opens the directory identified by the given path, returning a {@code
* SecureDirectoryStream} to iterate over the entries in the directory.
*
* <p> This method works in exactly the manner specified by the {@link
* Path#newDirectoryStream newDirectoryStream} method for the case that
* the {@code path} parameter is an {@link Path#isAbsolute absolute} path.
* When the parameter is a relative path then the directory to open is
* relative to this open directory. The {@code followLinks} parameter
* determines if links should be followed. If this parameter is {@code
* false} and the file is a symbolic link then this method fails (by
* throwing an I/O exception).
*
* <p> The new directory stream, once created, is not dependent upon the
* directory stream used to create it. Closing this directory stream has no
* effect upon newly created directory stream.
*
* @param path
* The path to the directory to open
* @param followLinks
* {@code true} if the links should be followed
* @param filter
* The directory stream filter or {@code null}.
*
* @return A new and open {@code SecureDirectoryStream} object
*
* @throws ClosedDirectoryStreamException
* If the directory stream is closed
* @throws NotDirectoryException
* If the file could not otherwise be opened because it is not
* a directory <i>(optional specific exception)</i>
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkRead(String) checkRead}
* method is invoked to check read access to the directory.
*/
public abstract SecureDirectoryStream newDirectoryStream(Path path,
boolean followLinks,
DirectoryStream.Filter<? super Path> filter)
throws IOException;
/**
* Opens or creates a file in this directory, returning a seekable byte
* channel to access the file.
*
* <p> This method works in exactly the manner specified by the {@link
* Path#newByteChannel Path.newByteChannel} method for the
* case that the {@code path} parameter is an {@link Path#isAbsolute absolute}
* path. When the parameter is a relative path then the file to open or
* create is relative to this open directory. In addition to the options
* defined by the {@code Path.newByteChannel} method, the {@link
* LinkOption#NOFOLLOW_LINKS NOFOLLOW_LINKS} option may be used to
* ensure that this method fails if the file is a symbolic link.
*
* <p> The channel, once created, is not dependent upon the directory stream
* used to create it. Closing this directory stream has no effect upon the
* channel.
*
* @param path
* The path of the file to open open or create
* @param options
* Options specifying how the file is opened
* @param attrs
* An optional list of attributes to set atomically when creating
* the file
*
* @throws ClosedDirectoryStreamException
* If the directory stream is closed
* @throws IllegalArgumentException
* If the set contains an invalid combination of options
* @throws UnsupportedOperationException
* If an unsupported open option is specified or the array contains
* attributes that cannot be set atomically when creating the file
* @throws FileAlreadyExistsException
* If a file of that name already exists and the {@link
* StandardOpenOption#CREATE_NEW CREATE_NEW} option is specified
* <i>(optional specific exception)</i>
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkRead(String) checkRead}
* method is invoked to check read access to the path if the file
* is opened for reading. The {@link SecurityManager#checkWrite(String)
* checkWrite} method is invoked to check write access to the path
* if the file is opened for writing.
*/
public abstract SeekableByteChannel newByteChannel(Path path,
Set<? extends OpenOption> options,
FileAttribute<?>... attrs)
throws IOException;
/**
* Deletes a file.
*
* <p> Unlike the {@link FileRef#delete delete()} method, this method
* does not first examine the file to determine if the file is a directory.
* Whether a directory is deleted by this method is system dependent and
* therefore not specified. If the file is a symbolic-link then the link is
* deleted (not the final target of the link). When the parameter is a
* relative path then the file to delete is relative to this open directory.
*
* @param path
* The path of the file to delete
*
* @throws ClosedDirectoryStreamException
* If the directory stream is closed
* @throws NoSuchFileException
* If the the file does not exist <i>(optional specific exception)</i>
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkDelete(String) checkDelete}
* method is invoked to check delete access to the file
*/
public abstract void deleteFile(Path path) throws IOException;
/**
* Deletes a directory.
*
* <p> Unlike the {@link FileRef#delete delete()} method, this method
* does not first examine the file to determine if the file is a directory.
* Whether non-directories are deleted by this method is system dependent and
* therefore not specified. When the parameter is a relative path then the
* directory to delete is relative to this open directory.
*
* @param path
* The path of the directory to delete
*
* @throws ClosedDirectoryStreamException
* If the directory stream is closed
* @throws NoSuchFileException
* If the the directory does not exist <i>(optional specific exception)</i>
* @throws DirectoryNotEmptyException
* If the directory could not otherwise be deleted because it is
* not empty <i>(optional specific exception)</i>
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkDelete(String) checkDelete}
* method is invoked to check delete access to the directory
*/
public abstract void deleteDirectory(Path path) throws IOException;
/**
* Move a file from this directory to another directory.
*
* <p> This method works in a similar manner to {@link Path#moveTo moveTo}
* method when the {@link StandardCopyOption#ATOMIC_MOVE ATOMIC_MOVE} option
* is specified. That is, this method moves a file as an atomic file system
* operation. If the {@code srcpath} parameter is an {@link Path#isAbsolute
* absolute} path then it locates the source file. If the parameter is a
* relative path then it is located relative to this open directory. If
* the {@code targetpath} parameter is absolute then it locates the target
* file (the {@code targetdir} parameter is ignored). If the parameter is
* a relative path it is located relative to the open directory identified
* by the {@code targetdir} parameter. In all cases, if the target file
* exists then it is implementation specific if it is replaced or this
* method fails.
*
* @param srcpath
* The name of the file to move
* @param targetdir
* The destination directory
* @param targetpath
* The name to give the file in the destination directory
*
* @throws ClosedDirectoryStreamException
* If this or the target directory stream is closed
* @throws FileAlreadyExistsException
* The file already exists in the target directory and cannot
* be replaced <i>(optional specific exception)</i>
* @throws AtomicMoveNotSupportedException
* The file cannot be moved as an atomic file system operation
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, the {@link SecurityManager#checkWrite(String) checkWrite}
* method is invoked to check write access to both the source and
* target file.
*/
public abstract void move(Path srcpath, SecureDirectoryStream targetdir, Path targetpath)
throws IOException;
/**
* Returns a new file attribute view to access the file attributes of this
* directory.
*
* <p> The resulting file attribute view can be used to read or update the
* attributes of this (open) directory. The {@code type} parameter specifies
* the type of the attribute view and the method returns an instance of that
* type if supported. Invoking this method to obtain a {@link
* BasicFileAttributeView} always returns an instance of that class that is
* bound to this open directory.
*
* <p> The state of resulting file attribute view is intimately connected
* to this directory stream. Once the directory stream is {@link #close closed},
* then all methods to read or update attributes will throw {@link
* ClosedDirectoryStreamException ClosedDirectoryStreamException}.
*
* @param type
* The {@code Class} object corresponding to the file attribute view
*
* @return A new file attribute view of the specified type bound to
* this directory stream, or {@code null} if the attribute view
* type is not available
*/
public abstract <V extends FileAttributeView> V getFileAttributeView(Class<V> type);
/**
* Returns a new file attribute view to access the file attributes of a file
* in this directory.
*
* <p> The resulting file attribute view can be used to read or update the
* attributes of file in this directory. The {@code type} parameter specifies
* the type of the attribute view and the method returns an instance of that
* type if supported. Invoking this method to obtain a {@link
* BasicFileAttributeView} always returns an instance of that class that is
* bound to the file in the directory.
*
* <p> The state of resulting file attribute view is intimately connected
* to this directory stream. Once the directory stream {@link #close closed},
* then all methods to read or update attributes will throw {@link
* ClosedDirectoryStreamException ClosedDirectoryStreamException}. The
* file is not required to exist at the time that the file attribute view
* is created but methods to read or update attributes of the file will
* fail when invoked and the file does not exist.
*
* @param path
* The path of the file
* @param type
* The {@code Class} object corresponding to the file attribute view
* @param options
* Options indicating how symbolic links are handled
*
* @return A new file attribute view of the specified type bound to a
* this directory stream, or {@code null} if the attribute view
* type is not available
*
*/
public abstract <V extends FileAttributeView> V getFileAttributeView(Path path,
Class<V> type,
LinkOption... options);
}

121
jdk/src/share/classes/java/nio/file/SimpleFileVisitor.java Normal file
View file

@ -0,0 +1,121 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
import java.nio.file.attribute.BasicFileAttributes;
import java.io.IOException;
import java.io.IOError;
/**
* A simple visitor of files with default behavior to visit all files and to
* re-throw I/O errors.
*
* <p> Methods in this class may be overridden subject to their general contract.
*
* @param <T> The type of reference to the files
*
* @since 1.7
*/
public class SimpleFileVisitor<T extends FileRef> implements FileVisitor<T> {
/**
* Initializes a new instance of this class.
*/
protected SimpleFileVisitor() {
}
/**
* Invoked for a directory before entries in the directory are visited.
*
* <p> Unless overridden, this method returns {@link FileVisitResult#CONTINUE
* CONTINUE}.
*/
@Override
public FileVisitResult preVisitDirectory(T dir) {
return FileVisitResult.CONTINUE;
}
/**
* Invoked for a directory that could not be opened.
*
* <p> Unless overridden, this method throws {@link IOError} with the I/O
* exception as cause.
*
* @throws IOError
* With the I/O exception thrown when the attempt to open the
* directory failed
*/
@Override
public FileVisitResult preVisitDirectoryFailed(T dir, IOException exc) {
throw new IOError(exc);
}
/**
* Invoked for a file in a directory.
*
* <p> Unless overridden, this method returns {@link FileVisitResult#CONTINUE
* CONTINUE}.
*/
@Override
public FileVisitResult visitFile(T file, BasicFileAttributes attrs) {
return FileVisitResult.CONTINUE;
}
/**
* Invoked for a file when its basic file attributes could not be read.
*
* <p> Unless overridden, this method throws {@link IOError} with the I/O
* exception as cause.
*
* @throws IOError
* With the I/O exception thrown when the attempt to read the file
* attributes failed
*/
@Override
public FileVisitResult visitFileFailed(T file, IOException exc) {
throw new IOError(exc);
}
/**
* Invoked for a directory after entries in the directory, and all of their
* descendants, have been visited.
*
* <p> Unless overridden, this method returns {@link FileVisitResult#CONTINUE
* CONTINUE} if the directory iteration completes without an I/O exception;
* otherwise this method throws {@link IOError} with the I/O exception as
* cause.
*
* @throws IOError
* If iteration of the directory completed prematurely due to an
* I/O error
*/
@Override
public FileVisitResult postVisitDirectory(T dir, IOException exc) {
if (exc != null)
throw new IOError(exc);
return FileVisitResult.CONTINUE;
}
}

47
jdk/src/share/classes/java/nio/file/StandardCopyOption.java Normal file
View file

@ -0,0 +1,47 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Defines the standard copy options.
*
* @since 1.7
*/
public enum StandardCopyOption implements CopyOption {
/**
* Replace an existing file if it exists.
*/
REPLACE_EXISTING,
/**
* Copy attributes to the new file.
*/
COPY_ATTRIBUTES,
/**
* Move the file as an atomic file system operation.
*/
ATOMIC_MOVE;
}

125
jdk/src/share/classes/java/nio/file/StandardOpenOption.java Normal file
View file

@ -0,0 +1,125 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Defines the standard open options.
*
* @since 1.7
*/
public enum StandardOpenOption implements OpenOption {
/**
* Open for read access.
*/
READ,
/**
* Open for write access.
*/
WRITE,
/**
* If the file is opened for {@link #WRITE} access then bytes will be written
* to the end of the file rather than the beginning.
*
* <p> If the file is opened for write access by other programs, then it
* is file system specific if writing to the end of the file is atomic.
*/
APPEND,
/**
* If the file already exists and it is opened for {@link #WRITE}
* access, then its length is truncated to 0. This option is ignored
* if the file is opened only for {@link #READ} access.
*/
TRUNCATE_EXISTING,
/**
* Create a new file if it does not exist.
* This option is ignored if the {@link #CREATE_NEW} option is also set.
* The check for the existence of the file and the creation of the file
* if it does not exist is atomic with respect to other file system
* operations.
*/
CREATE,
/**
* Create a new file, failing if the file already exists.
* The check for the existence of the file and the creation of the file
* if it does not exist is atomic with respect to other file system
* operations.
*/
CREATE_NEW,
/**
* Delete on close. When this option is present then the implementation
* makes a <em>best effort</em> attempt to delete the file when closed
* by the appropriate {@code close} method. If the {@code close} method is
* not invoked then a <em>best effort</em> attempt is made to delete the
* file when the Java virtual machine terminates (either normally, as
* defined by the Java Language Specification, or where possible, abnormally).
* This option is primarily intended for use with <em>work files</em> that
* are used solely by a single instance of the Java virtual machine. This
* option is not recommended for use when opening files that are open
* concurrently by other entities. Many of the details as to when and how
* the file is deleted are implementation specific and therefore not
* specified. In particular, an implementation may be unable to guarantee
* that it deletes the expected file when replaced by an attacker while the
* file is open. Consequently, security sensitive applications should take
* care when using this option.
*
* <p> For security reasons, this option may imply the {@link
* LinkOption#NOFOLLOW_LINKS} option. In other words, if the option is present
* when opening an existing file that is a symbolic link then it may fail
* (by throwing {@link java.io.IOException}).
*/
DELETE_ON_CLOSE,
/**
* Sparse file. When used with the {@link #CREATE_NEW} option then this
* option provides a <em>hint</em> that the new file will be sparse. The
* option is ignored when the file system does not support the creation of
* sparse files.
*/
SPARSE,
/**
* Requires that every update to the file's content or metadata be written
* synchronously to the underlying storage device.
*
* @see <a href="package-summary.html#integrity">Synchronized I/O file integrity</a>
*/
SYNC,
/**
* Requires that every update to the file's content be written
* synchronously to the underlying storage device.
*
* @see <a href="package-summary.html#integrity">Synchronized I/O file integrity</a>
*/
DSYNC;
}

94
jdk/src/share/classes/java/nio/file/StandardWatchEventKind.java Normal file
View file

@ -0,0 +1,94 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* Defines the <em>standard</em> event kinds.
*
* @since 1.7
*/
public class StandardWatchEventKind {
private StandardWatchEventKind() { }
/**
* A special event to indicate that events may have been lost or
* discarded.
*
* <p> The {@link WatchEvent#context context} for this event is
* implementation specific and may be {@code null}. The event {@link
* WatchEvent#count count} may be greater than {@code 1}.
*
* @see WatchService
*/
public static final WatchEvent.Kind<Void> OVERFLOW =
new StdWatchEventKind<Void>("OVERFLOW", Void.class);
/**
* Directory entry created.
*
* <p> When a directory is registered for this event then the {@link WatchKey}
* is queued when it is observed that an entry is created in the directory
* or renamed into the directory. The event {@link WatchEvent#count count}
* for this event is always {@code 1}.
*/
public static final WatchEvent.Kind<Path> ENTRY_CREATE =
new StdWatchEventKind<Path>("ENTRY_CREATE", Path.class);
/**
* Directory entry deleted.
*
* <p> When a directory is registered for this event then the {@link WatchKey}
* is queued when it is observed that an entry is deleted or renamed out of
* the directory. The event {@link WatchEvent#count count} for this event
* is always {@code 1}.
*/
public static final WatchEvent.Kind<Path> ENTRY_DELETE =
new StdWatchEventKind<Path>("ENTRY_DELETE", Path.class);
/**
* Directory entry modified.
*
* <p> When a directory is registered for this event then the {@link WatchKey}
* is queued when it is observed that an entry in the directory has been
* modified. The event {@link WatchEvent#count count} for this event is
* {@code 1} or greater.
*/
public static final WatchEvent.Kind<Path> ENTRY_MODIFY =
new StdWatchEventKind<Path>("ENTRY_MODIFY", Path.class);
private static class StdWatchEventKind<T> implements WatchEvent.Kind<T> {
private final String name;
private final Class<T> type;
StdWatchEventKind(String name, Class<T> type) {
this.name = name;
this.type = type;
}
@Override public String name() { return name; }
@Override public Class<T> type() { return type; }
@Override public String toString() { return name; }
}
}

116
jdk/src/share/classes/java/nio/file/WatchEvent.java Normal file
View file

@ -0,0 +1,116 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
/**
* An event or a repeated event for an object that is registered with a {@link
* WatchService}.
*
* <p> An event is classified by its {@link #kind() kind} and has a {@link
* #count() count} to indicate the number of times that the event has been
* observed. This allows for efficient representation of repeated events. The
* {@link #context() context} method returns any context associated with
* the event. In the case of a repeated event then the context is the same for
* all events.
*
* <p> Watch events are immutable and safe for use by multiple concurrent
* threads.
*
* @param <T> The type of the context object associated with the event
*
* @since 1.7
*/
public abstract class WatchEvent<T> {
/**
* An event kind, for the purposes of identification.
*
* @since 1.7
* @see StandardWatchEventKind
*/
public static interface Kind<T> {
/**
* Returns the name of the event kind.
*/
String name();
/**
* Returns the type of the {@link WatchEvent#context context} value.
*/
Class<T> type();
}
/**
* Initializes a new instance of this class.
*/
protected WatchEvent() { }
/**
* An event modifier that qualifies how a {@link Watchable} is registered
* with a {@link WatchService}.
*
* <p> This release does not define any <em>standard</em> modifiers.
*
* @since 1.7
* @see Watchable#register
*/
public static interface Modifier {
/**
* Returns the name of the modifier.
*/
String name();
}
/**
* Returns the event kind.
*
* @return The event kind
*/
public abstract Kind<T> kind();
/**
* Returns the event count. If the event count is greater than {@code 1}
* then this is a repeated event.
*
* @return The event count
*/
public abstract int count();
/**
* Returns the context for the event.
*
* <p> In the case of {@link StandardWatchEventKind#ENTRY_CREATE ENTRY_CREATE},
* {@link StandardWatchEventKind#ENTRY_DELETE ENTRY_DELETE}, and {@link
* StandardWatchEventKind#ENTRY_MODIFY ENTRY_MODIFY} events the context is
* a {@code Path} that is the {@link Path#relativize relative} path between
* the directory registered with the watch service, and the entry that is
* created, deleted, or modified.
*
* @return The event context; may be {@code null}
*/
public abstract T context();
}

138
jdk/src/share/classes/java/nio/file/WatchKey.java Normal file
View file

@ -0,0 +1,138 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
import java.util.List;
/**
* A token representing the registration of a {@link Watchable watchable} object
* with a {@link WatchService}.
*
* <p> A watch key is created when a watchable object is registered with a watch
* service. The key remains {@link #isValid valid} until:
* <ol>
* <li> It is cancelled, explicitly, by invoking its {@link #cancel cancel}
* method, or</li>
* <li> Cancelled implicitly, because the object is no longer accessible,
* or </li>
* <li> By {@link WatchService#close closing} the watch service. </li>
* </ol>
*
* <p> A watch key has a state. When initially created the key is said to be
* <em>ready</em>. When an event is detected then the key is <em>signalled</em>
* and queued so that it can be retrieved by invoking the watch service's {@link
* WatchService#poll() poll} or {@link WatchService#take() take} methods. Once
* signalled, a key remains in this state until its {@link #reset reset} method
* is invoked to return the key to the ready state. Events detected while the
* key is in the signalled state are queued but do not cause the key to be
* re-queued for retrieval from the watch service. Events are retrieved by
* invoking the key's {@link #pollEvents pollEvents} method. This method
* retrieves and removes all events accumulated for the object. When initially
* created, a watch key has no pending events. Typically events are retrieved
* when the key is in the signalled state leading to the following idiom:
*
* <pre>
* for (;;) {
* // retrieve key
* WatchKey key = watcher.take();
*
* // process events
* for (WatchEvent&lt;?&gt; event: key.pollEvents()) {
* :
* }
*
* // reset the key
* boolean valid = key.reset();
* if (!valid) {
* // object no longer registered
* }
* }
* </pre>
*
* <p> Watch keys are safe for use by multiple concurrent threads. Where there
* are several threads retrieving signalled keys from a watch service then care
* should be taken to ensure that the {@code reset} method is only invoked after
* the events for the object have been processed. This ensures that one thread
* is processing the events for an object at any time.
*
* @since 1.7
*/
public abstract class WatchKey {
/**
* Initializes a new instance of this class.
*/
protected WatchKey() { }
/**
* Tells whether or not this watch key is valid.
*
* <p> A watch key is valid upon creation and remains until it is cancelled,
* or its watch service is closed.
*
* @return {@code true} if, and only if, this watch key is valid
*/
public abstract boolean isValid();
/**
* Retrieves and removes all pending events for this watch key, returning
* a {@code List} of the events that were retrieved.
*
* <p> Note that this method does not wait if there are no events pending.
*
* @return The list of the events retrieved
*/
public abstract List<WatchEvent<?>> pollEvents();
/**
* Resets this watch key.
*
* <p> If this watch key has been cancelled or this watch key is already in
* the ready state then invoking this method has no effect. Otherwise
* if there are pending events for the object then this watch key is
* immediately re-queued to the watch service. If there are no pending
* events then the watch key is put into the ready state and will remain in
* that state until an event is detected or the watch key is cancelled.
*
* @return {@code true} if the watch key is valid and has been reset;
* {@code false} if the watch key could not be reset because it is
* no longer {@link #isValid valid}
*/
public abstract boolean reset();
/**
* Cancels the registration with the watch service. Upon return the watch key
* will be invalid. If the watch key is enqueued, waiting to be retrieved
* from the watch service, then it will remain in the queue until it is
* removed. Pending events, if any, remain pending and may be retrieved by
* invoking the {@link #pollEvents pollEvents} method event after the key is
* cancelled.
*
* <p> If this watch key has already been cancelled then invoking this
* method has no effect. Once cancelled, a watch key remains forever invalid.
*/
public abstract void cancel();
}

178
jdk/src/share/classes/java/nio/file/WatchService.java Normal file
View file

@ -0,0 +1,178 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
import java.io.Closeable;
import java.io.IOException;
import java.util.concurrent.TimeUnit;
/**
* A watch service that <em>watches</em> registered objects for changes and
* events. For example a file manager may use a watch service to monitor a
* directory for changes so that it can update its display of the list of files
* when files are created or deleted.
*
* <p> A {@link Watchable} object is registered with a watch service by invoking
* its {@link Watchable#register register} method, returning a {@link WatchKey}
* to represent the registration. When an event for an object is detected the
* key is <em>signalled</em>, and if not currently signalled, it is queued to
* the watch service so that it can be retrieved by consumers that invoke the
* {@link #poll() poll} or {@link #take() take} methods to retrieve keys
* and process events. Once the events have been processed the consumer
* invokes the key's {@link WatchKey#reset reset} method to reset the key which
* allows the key to be signalled and re-queued with further events.
*
* <p> Registration with a watch service is cancelled by invoking the key's
* {@link WatchKey#cancel cancel} method. A key that is queued at the time that
* it is cancelled remains in the queue until it is retrieved. Depending on the
* object, a key may be cancelled automatically. For example, suppose a
* directory is watched and the watch service detects that it has been deleted
* or its file system is no longer accessible. When a key is cancelled in this
* manner it is signalled and queued, if not currently signalled. To ensure
* that the consumer is notified the return value from the {@code reset}
* method indicates if the key is valid.
*
* <p> A watch service is safe for use by multiple concurrent consumers. To
* ensure that only one consumer processes the events for a particular object at
* any time then care should be taken to ensure that the key's {@code reset}
* method is only invoked after its events have been processed. The {@link
* #close close} method may be invoked at any time to close the service causing
* any threads waiting to retrieve keys, to throw {@code
* ClosedWatchServiceException}.
*
* <p> File systems may report events faster than they can be retrieved or
* processed and an implementation may impose an unspecified limit on the number
* of events that it may accumulate. Where an implementation <em>knowingly</em>
* discards events then it arranges for the key's {@link WatchKey#pollEvents
* pollEvents} method to return an element with an event type of {@link
* StandardWatchEventKind#OVERFLOW OVERFLOW}. This event can be used by the
* consumer as a trigger to re-examine the state of the object.
*
* <p> When an event is reported to indicate that a file in a watched directory
* has been modified then there is no guarantee that the program (or programs)
* that have modified the file have completed. Care should be taken to coordinate
* access with other programs that may be updating the file.
* The {@link java.nio.channels.FileChannel FileChannel} class defines methods
* to lock regions of a file against access by other programs.
*
* <h4>Platform dependencies</h4>
*
* <p> The implementation that observes events from the file system is intended
* to map directly on to the native file event notification facility where
* available, or to use a primitive mechanism, such as polling, when a native
* facility is not available. Consequently, many of the details on how events
* are detected, their timeliness, and whether their ordering is preserved are
* highly implementation specific. For example, when a file in a watched
* directory is modified then it may result in a single {@link
* StandardWatchEventKind#ENTRY_MODIFY ENTRY_MODIFY} event in some
* implementations but several events in other implementations. Short-lived
* files (meaning files that are deleted very quickly after they are created)
* may not be detected by primitive implementations that periodically poll the
* file system to detect changes.
*
* <p> If a watched file is not located on a local storage device then it is
* implementation specific if changes to the file can be detected. In particular,
* it is not required that changes to files carried out on remote systems be
* detected.
*
* @since 1.7
*
* @see FileSystem#newWatchService
*/
public abstract class WatchService
implements Closeable
{
/**
* Initializes a new instance of this class.
*/
protected WatchService() { }
/**
* Closes this watch service.
*
* <p> If a thread is currently blocked in the {@link #take take} or {@link
* #poll(long,TimeUnit) poll} methods waiting for a key to be queued then
* it immediately receives a {@link ClosedWatchServiceException}. Any
* valid keys associated with this watch service are {@link WatchKey#isValid
* invalidated}.
*
* <p> After a watch service is closed, any further attempt to invoke
* operations upon it will throw {@link ClosedWatchServiceException}.
* If this watch service is already closed then invoking this method
* has no effect.
*
* @throws IOException
* If an I/O error occurs
*/
@Override
public abstract void close() throws IOException;
/**
* Retrieves and removes the next watch key, or {@code null} if none are
* present.
*
* @return The next watch key, or {@code null}
*
* @throws ClosedWatchServiceException
* If this watch service is closed
*/
public abstract WatchKey poll();
/**
* Retrieves and removes the next watch key, waiting if necessary up to the
* specified wait time if none are yet present.
*
* @param timeout
* how to wait before giving up, in units of unit
* @param unit
* a {@code TimeUnit} determining how to interpret the timeout
* parameter
*
* @return The next watch key, or {@code null}
*
* @throws ClosedWatchServiceException
* If this watch service is closed, or it is closed while waiting
* for the next key
* @throws InterruptedException
* If interrupted while waiting
*/
public abstract WatchKey poll(long timeout, TimeUnit unit)
throws InterruptedException;
/**
* Retrieves and removes next watch key, waiting if none are yet present.
*
* @return The next watch key
*
* @throws ClosedWatchServiceException
* If this watch service is closed, or it is closed while waiting
* for the next key
* @throws InterruptedException
* If interrupted while waiting
*/
public abstract WatchKey take() throws InterruptedException;
}

127
jdk/src/share/classes/java/nio/file/Watchable.java Normal file
View file

@ -0,0 +1,127 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file;
import java.io.IOException;
/**
* An object that may be registered with a watch service so that it can be
* <em>watched</em> for changes and events.
*
* <p> This interface defines the {@link #register register} method to register
* the object with a {@link WatchService} returning a {@link WatchKey} to
* represent the registration. An object may be registered with more than one
* watch service. Registration with a watch service is cancelled by invoking the
* key's {@link WatchKey#cancel cancel} method.
*
* @since 1.7
*
* @see Path#register
*/
public interface Watchable {
/**
* Registers an object with a watch service.
*
* <p> If the file system object identified by this object is currently
* registered with the watch service then the watch key, representing that
* registration, is returned after changing the event set or modifiers to
* those specified by the {@code events} and {@code modifiers} parameters.
* Changing the event set does not cause pending events for the object to be
* discarded. Objects are automatically registered for the {@link
* StandardWatchEventKind#OVERFLOW OVERFLOW} event. This event is not
* required to be present in the array of events.
*
* <p> Otherwise the file system object has not yet been registered with the
* given watch service, so it is registered and the resulting new key is
* returned.
*
* <p> Implementations of this interface should specify the events they
* support.
*
* @param watcher
* The watch service to which this object is to be registered
* @param events
* The events for which this object should be registered
* @param modifiers
* The modifiers, if any, that modify how the object is registered
*
* @return A key representing the registration of this object with the
* given watch service
*
* @throws UnsupportedOperationException
* If unsupported events or modifiers are specified
* @throws IllegalArgumentException
* If an invalid of combination of events are modifiers are specified
* @throws ClosedWatchServiceException
* If the watch service is closed
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* If a security manager is installed and it denies an unspecified
* permission required to monitor this object. Implementations of
* this interface should specify the permission checks.
*/
WatchKey register(WatchService watcher,
WatchEvent.Kind<?>[] events,
WatchEvent.Modifier... modifiers)
throws IOException;
/**
* Registers an object with a watch service.
*
* <p> An invocation of this method behaves in exactly the same way as the
* invocation
* <pre>
* watchable.{@link #register(WatchService,WatchEvent.Kind[],WatchEvent.Modifier[]) register}(watcher, events, new WatchEvent.Modifier[0]);
* </pre>
*
* @param watcher
* The watch service to which this object is to be registered
* @param events
* The events for which this object should be registered
*
* @return A key representing the registration of this object with the
* given watch service
*
* @throws UnsupportedOperationException
* If unsupported events are specified
* @throws IllegalArgumentException
* If an invalid of combination of events are specified
* @throws ClosedWatchServiceException
* If the watch service is closed
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* If a security manager is installed and it denies an unspecified
* permission required to monitor this object. Implementations of
* this interface should specify the permission checks.
*/
WatchKey register(WatchService watcher, WatchEvent.Kind<?>... events)
throws IOException;
}

394
jdk/src/share/classes/java/nio/file/attribute/AclEntry.java Normal file
View file

@ -0,0 +1,394 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file.attribute;
import java.util.*;
/**
* An entry in an access control list (ACL).
*
* <p> The ACL entry represented by this class is based on the ACL model
* specified in <a href="http://www.ietf.org/rfc/rfc3530.txt"><i>RFC&nbsp;3530:
* Network File System (NFS) version 4 Protocol</i></a>. Each entry has four
* components as follows:
*
* <ol>
* <li><p> The {@link #type() type} component determines if the entry
* grants or denies access. </p></li>
*
* <li><p> The {@link #principal() principal} component, sometimes called the
* "who" component, is a {@link UserPrincipal} corresponding to the identity
* that the entry grants or denies access
* </p></li>
*
* <li><p> The {@link #permissions permissions} component is a set of
* {@link AclEntryPermission permissions}
* </p></li>
*
* <li><p> The {@link #flags flags} component is a set of {@link AclEntryFlag
* flags} to indicate how entries are inherited and propagated </p></li>
* </ol>
*
* <p> ACL entries are created using an associated {@link Builder} object by
* invoking its {@link Builder#build build} method.
*
* <p> ACL entries are immutable and are safe for use by multiple concurrent
* threads.
*
* @since 1.7
*/
public final class AclEntry {
private final AclEntryType type;
private final UserPrincipal who;
private final Set<AclEntryPermission> perms;
private final Set<AclEntryFlag> flags;
// cached hash code
private volatile int hash;
// private constructor
private AclEntry(AclEntryType type,
UserPrincipal who,
Set<AclEntryPermission> perms,
Set<AclEntryFlag> flags)
{
this.type = type;
this.who = who;
this.perms = perms;
this.flags = flags;
}
/**
* A builder of {@link AclEntry} objects.
*
* <p> A {@code Builder} object is obtained by invoking one of the {@link
* AclEntry#newBuilder newBuilder} methods defined by the {@code AclEntry}
* class.
*
* <p> Builder objects are mutable and are not safe for use by multiple
* concurrent threads without appropriate synchronization.
*
* @since 1.7
*/
public static final class Builder {
private AclEntryType type;
private UserPrincipal who;
private Set<AclEntryPermission> perms;
private Set<AclEntryFlag> flags;
private Builder(AclEntryType type,
UserPrincipal who,
Set<AclEntryPermission> perms,
Set<AclEntryFlag> flags)
{
assert perms != null && flags != null;
this.type = type;
this.who = who;
this.perms = perms;
this.flags = flags;
}
/**
* Constructs an {@link AclEntry} from the components of this builder.
* The type and who components are required to have been set in order
* to construct an {@code AclEntry}.
*
* @return A new ACL entry
*
* @throws IllegalStateException
* If the type or who component have not been set.
*/
public AclEntry build() {
if (type == null)
throw new IllegalStateException("Missing type component");
if (who == null)
throw new IllegalStateException("Missing who component");
return new AclEntry(type, who, perms, flags);
}
/**
* Sets the type component of this builder.
*
* @return This builder
*/
public Builder setType(AclEntryType type) {
if (type == null)
throw new NullPointerException();
this.type = type;
return this;
}
/**
* Sets the principal component of this builder.
*
* @return This builder
*/
public Builder setPrincipal(UserPrincipal who) {
if (who == null)
throw new NullPointerException();
this.who = who;
return this;
}
// check set only contains elements of the given type
private static void checkSet(Set<?> set, Class<?> type) {
for (Object e: set) {
if (e == null)
throw new NullPointerException();
type.cast(e);
}
}
/**
* Sets the permissions component of this builder. On return, the
* permissions component of this builder is a copy of the given set.
*
* @return This builder
*
* @throws ClassCastException
* If the sets contains elements that are not of type {@code
* AclEntryPermission}
*/
public Builder setPermissions(Set<AclEntryPermission> perms) {
// copy and check for erroneous elements
perms = new HashSet<AclEntryPermission>(perms);
checkSet(perms, AclEntryPermission.class);
this.perms = perms;
return this;
}
/**
* Sets the permissions component of this builder. On return, the
* permissions component of this builder is a copy of the permissions in
* the given array.
*
* @return This builder
*/
public Builder setPermissions(AclEntryPermission... perms) {
Set<AclEntryPermission> set =
new HashSet<AclEntryPermission>(perms.length);
// copy and check for null elements
for (AclEntryPermission p: perms) {
if (p == null)
throw new NullPointerException();
set.add(p);
}
this.perms = set;
return this;
}
/**
* Sets the flags component of this builder. On return, the flags
* component of this builder is a copy of the given set.
*
* @return This builder
*
* @throws ClassCastException
* If the sets contains elements that are not of type {@code
* AclEntryFlag}
*/
public Builder setFlags(Set<AclEntryFlag> flags) {
// copy and check for erroneous elements
flags = new HashSet<AclEntryFlag>(flags);
checkSet(flags, AclEntryFlag.class);
this.flags = flags;
return this;
}
/**
* Sets the flags component of this builder. On return, the flags
* component of this builder is a copy of the flags in the given
* array.
*
* @return This builder
*/
public Builder setFlags(AclEntryFlag... flags) {
Set<AclEntryFlag> set = new HashSet<AclEntryFlag>(flags.length);
// copy and check for null elements
for (AclEntryFlag f: flags) {
if (f == null)
throw new NullPointerException();
set.add(f);
}
this.flags = set;
return this;
}
}
/**
* Constructs a new builder. The initial value of the type and who
* components is {@code null}. The initial value of the permissions and
* flags components is the empty set.
*
* @return A new builder
*/
public static Builder newBuilder() {
Set<AclEntryPermission> perms = Collections.emptySet();
Set<AclEntryFlag> flags = Collections.emptySet();
return new Builder(null, null, perms, flags);
}
/**
* Constructs a new builder with the components of an existing ACL entry.
*
* @param entry
* An ACL entry
*
* @return A new builder
*/
public static Builder newBuilder(AclEntry entry) {
return new Builder(entry.type, entry.who, entry.perms, entry.flags);
}
/**
* Returns the ACL entry type.
*/
public AclEntryType type() {
return type;
}
/**
* Returns the principal component.
*/
public UserPrincipal principal() {
return who;
}
/**
* Returns a copy of the permissions component.
*
* <p> The returned set is a modifiable copy of the permissions.
*/
public Set<AclEntryPermission> permissions() {
return new HashSet<AclEntryPermission>(perms);
}
/**
* Returns a copy of the flags component.
*
* <p> The returned set is a modifiable copy of the flags.
*/
public Set<AclEntryFlag> flags() {
return new HashSet<AclEntryFlag>(flags);
}
/**
* Compares the specified object with this ACL entry for equality.
*
* <p> If the given object is not an {@code AclEntry} then this method
* immediately returns {@code false}.
*
* <p> For two ACL entries to be considered equals requires that they are
* both the same type, their who components are equal, their permissions
* components are equal, and their flags components are equal.
*
* <p> This method satisfies the general contract of the {@link
* java.lang.Object#equals(Object) Object.equals} method. </p>
*
* @param ob The object to which this object is to be compared
*
* @return {@code true} if, and only if, the given object is an AclEntry that
* is identical to this AclEntry
*/
@Override
public boolean equals(Object ob) {
if (ob == this)
return true;
if (ob == null || !(ob instanceof AclEntry))
return false;
AclEntry other = (AclEntry)ob;
if (this.type != other.type)
return false;
if (!this.who.equals(other.who))
return false;
if (!this.perms.equals(other.perms))
return false;
if (!this.flags.equals(other.flags))
return false;
return true;
}
private static int hash(int h, Object o) {
return h * 127 + o.hashCode();
}
/**
* Returns the hash-code value for this ACL entry.
*
* <p> This method satisfies the general contract of the {@link
* Object#hashCode method}.
*/
@Override
public int hashCode() {
// return cached hash if available
if (hash != 0)
return hash;
int h = type.hashCode();
h = hash(h, who);
h = hash(h, perms);
h = hash(h, flags);
hash = h;
return hash;
}
/**
* Returns the string representation of this ACL entry.
*
* @return The string representation of this entry
*/
@Override
public String toString() {
StringBuilder sb = new StringBuilder();
// who
sb.append(who.getName());
sb.append(':');
// permissions
for (AclEntryPermission perm: perms) {
sb.append(perm.name());
sb.append('/');
}
sb.setLength(sb.length()-1); // drop final slash
sb.append(':');
// flags
if (!flags.isEmpty()) {
for (AclEntryFlag flag: flags) {
sb.append(flag.name());
sb.append('/');
}
sb.setLength(sb.length()-1); // drop final slash
sb.append(':');
}
// type
sb.append(type.name());
return sb.toString();
}
}

65
jdk/src/share/classes/java/nio/file/attribute/AclEntryFlag.java Normal file
View file

@ -0,0 +1,65 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file.attribute;
/**
* Defines the flags for used by the flags component of an ACL {@link AclEntry
* entry}.
*
* <p> In this release, this class does not define flags related to {@link
* AclEntryType#AUDIT} and {@link AclEntryType#ALARM} entry types.
*
* @since 1.7
*/
public enum AclEntryFlag {
/**
* Can be placed on a directory and indicates that the ACL entry should be
* added to each new non-directory file created.
*/
FILE_INHERIT,
/**
* Can be placed on a directory and indicates that the ACL entry should be
* added to each new directory created.
*/
DIRECTORY_INHERIT,
/**
* Can be placed on a directory to indicate that the ACL entry should not
* be placed on the newly created directory which is inheritable by
* subdirectories of the created directory.
*/
NO_PROPAGATE_INHERIT,
/**
* Can be placed on a directory but does not apply to the directory,
* only to newly created files/directories as specified by the
* {@link #FILE_INHERIT} and {@link #DIRECTORY_INHERIT} flags.
*/
INHERIT_ONLY;
}

130
jdk/src/share/classes/java/nio/file/attribute/AclEntryPermission.java Normal file
View file

@ -0,0 +1,130 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file.attribute;
/**
* Defines the permissions for use with the permissions component of an ACL
* {@link AclEntry entry}.
*
* @since 1.7
*/
public enum AclEntryPermission {
/**
* Permission to read the data of the file.
*/
READ_DATA,
/**
* Permission to modify the file's data.
*/
WRITE_DATA,
/**
* Permission to append data to a file.
*/
APPEND_DATA,
/**
* Permission to read the named attributes of a file.
*
* <p> <a href="http://www.ietf.org/rfc/rfc3530.txt">RFC&nbsp;3530: Network
* File System (NFS) version 4 Protocol</a> defines <em>named attributes</em>
* as opaque files associated with a file in the file system.
*/
READ_NAMED_ATTRS,
/**
* Permission to write the named attributes of a file.
*
* <p> <a href="http://www.ietf.org/rfc/rfc3530.txt">RFC&nbsp;3530: Network
* File System (NFS) version 4 Protocol</a> defines <em>named attributes</em>
* as opaque files associated with a file in the file system.
*/
WRITE_NAMED_ATTRS,
/**
* Permission to execute a file.
*/
EXECUTE,
/**
* Permission to delete a file or directory within a directory.
*/
DELETE_CHILD,
/**
* The ability to read (non-acl) file attributes.
*/
READ_ATTRIBUTES,
/**
* The ability to write (non-acl) file attributes.
*/
WRITE_ATTRIBUTES,
/**
* Permission to delete the file.
*/
DELETE,
/**
* Permission to read the ACL attribute.
*/
READ_ACL,
/**
* Permission to write the ACL attribute.
*/
WRITE_ACL,
/**
* Permission to change the owner.
*/
WRITE_OWNER,
/**
* Permission to access file locally at the server with synchronous reads
* and writes.
*/
SYNCHRONIZE;
/**
* Permission to list the entries of a directory (equal to {@link #READ_DATA})
*/
public static final AclEntryPermission LIST_DIRECTORY = READ_DATA;
/**
* Permission to add a new file to a directory (equal to {@link #WRITE_DATA})
*/
public static final AclEntryPermission ADD_FILE = WRITE_DATA;
/**
* Permission to create a subdirectory to a directory (equal to {@link #APPEND_DATA})
*/
public static final AclEntryPermission ADD_SUBDIRECTORY = APPEND_DATA;
}

56
jdk/src/share/classes/java/nio/file/attribute/AclEntryType.java Normal file
View file

@ -0,0 +1,56 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file.attribute;
/**
* A typesafe enumeration of the access control entry types.
*
* @since 1.7
*/
public enum AclEntryType {
/**
* Explicitly grants access to a file or directory.
*/
ALLOW,
/**
* Explicitly denies access to a file or directory.
*/
DENY,
/**
* Log, in a system dependent way, the access specified in the
* permissions component of the ACL entry.
*/
AUDIT,
/**
* Generate an alarm, in a system dependent way, the access specified in the
* permissions component of the ACL entry.
*/
ALARM
}

211
jdk/src/share/classes/java/nio/file/attribute/AclFileAttributeView.java Normal file
View file

@ -0,0 +1,211 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file.attribute;
import java.nio.file.*;
import java.util.List;
import java.io.IOException;
/**
* A file attribute view that supports reading or updating a file's Access
* Control Lists (ACL) or file owner attributes.
*
* <p> ACLs are used to specify access rights to file system objects. An ACL is
* an ordered list of {@link AclEntry access-control-entries}, each specifying a
* {@link UserPrincipal} and the level of access for that user principal. This
* file attribute view defines the {@link #getAcl() getAcl}, and {@link
* #setAcl(List) setAcl} methods to read and write ACLs based on the ACL
* model specified in <a href="http://www.ietf.org/rfc/rfc3530.txt"><i>RFC&nbsp;3530:
* Network File System (NFS) version 4 Protocol</i></a>. This file attribute view
* is intended for file system implementations that support the NFSv4 ACL model
* or have a <em>well-defined</em> mapping between the NFSv4 ACL model and the ACL
* model used by the file system. The details of such mapping are implementation
* dependent and are therefore unspecified.
*
* <p> This class also extends {@code FileOwnerAttributeView} so as to define
* methods to get and set the file owner.
*
* <p> When a file system provides access to a set of {@link FileStore
* file-systems} that are not homogeneous then only some of the file systems may
* support ACLs. The {@link FileStore#supportsFileAttributeView
* supportsFileAttributeView} method can be used to test if a file system
* supports ACLs.
*
* <a name="interop"><h4>Interoperability</h4></a>
*
* RFC&nbsp;3530 allows for special user identities to be used on platforms that
* support the POSIX defined access permissions. The special user identities
* are "{@code OWNER@}", "{@code GROUP@}", and "{@code EVERYONE@}". When both
* the {@code AclFileAttributeView} and the {@link PosixFileAttributeView}
* are supported then these special user identities may be included in ACL {@link
* AclEntry entries} that are read or written. The file system's {@link
* UserPrincipalLookupService} may be used to obtain a {@link UserPrincipal}
* to represent these special identities by invoking the {@link
* UserPrincipalLookupService#lookupPrincipalByName lookupPrincipalByName}
* method.
*
* <p> <b>Usage Example:</b>
* Suppose we wish to add an entry to an existing ACL to grant "joe" access:
* <pre>
* // lookup "joe"
* UserPrincipal joe = file.getFileSystem().getUserPrincipalLookupService()
* .lookupPrincipalByName("joe");
*
* // get view
* AclFileAttributeView view = file.newFileAttributeView(AclFileAttributeView.class);
*
* // create ACE to give "joe" read access
* AclEntry entry = AclEntry.newBuilder()
* .setType(AclEntryType.ALLOW)
* .setPrincipal(joe)
* .setPermissions(AclEntryPermission.READ_DATA, AclEntryPermission.READ_ATTRIBUTES)
* .build();
*
* // read ACL, insert ACE, re-write ACL
* List&lt;AclEntry&gt acl = view.getAcl();
* acl.add(0, entry); // insert before any DENY entries
* view.setAcl(acl);
* </pre>
*
* <h4> Dynamic Access </h4>
* <p> Where dynamic access to file attributes is required, the attributes
* supported by this attribute view are as follows:
* <blockquote>
* <table border="1" cellpadding="8">
* <tr>
* <th> Name </th>
* <th> Type </th>
* </tr>
* <tr>
* <td> "acl" </td>
* <td> {@link List}&lt;{@link AclEntry}&gt; </td>
* </tr>
* <tr>
* <td> "owner" </td>
* <td> {@link UserPrincipal} </td>
* </tr>
* </table>
* </blockquote>
*
* <p> The {@link #getAttribute getAttribute} or {@link #readAttributes
* readAttributes} methods may be used to read the ACL or owner attributes as if
* by invoking the {@link #getAcl getAcl} or {@link #getOwner getOwner} methods.
*
* <p> The {@link #setAttribute setAttribute} method may be used to update the
* ACL or owner attributes as if by invoking the {@link #setAcl setAcl} or {@link
* #setOwner setOwner} methods.
*
* <h4> Setting the ACL when creating a file </h4>
*
* <p> Implementations supporting this attribute view may also support setting
* the initial ACL when creating a file or directory. The initial ACL
* may be provided to methods such as {@link Path#createFile createFile} or {@link
* Path#createDirectory createDirectory} as an {@link FileAttribute} with {@link
* FileAttribute#name name} {@code "acl:acl"} and a {@link FileAttribute#value
* value} that is the list of {@code AclEntry} objects.
*
* <p> Where an implementation supports an ACL model that differs from the NFSv4
* defined ACL model then setting the initial ACL when creating the file must
* translate the ACL to the model supported by the file system. Methods that
* create a file should reject (by throwing {@link IOException IOException})
* any attempt to create a file that would be less secure as a result of the
* translation.
*
* @since 1.7
* @see Attributes#getAcl
* @see Attributes#setAcl
*/
public interface AclFileAttributeView
extends FileOwnerAttributeView
{
/**
* Returns the name of the attribute view. Attribute views of this type
* have the name {@code "acl"}.
*/
@Override
String name();
/**
* Reads the access control list.
*
* <p> When the file system uses an ACL model that differs from the NFSv4
* defined ACL model, then this method returns an ACL that is the translation
* of the ACL to the NFSv4 ACL model.
*
* <p> The returned list is modifiable so as to facilitate changes to the
* existing ACL. The {@link #setAcl setAcl} method is used to update
* the file's ACL attribute.
*
* @return An ordered list of {@link AclEntry entries} representing the
* ACL
*
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, and it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt>
* or its {@link SecurityManager#checkRead(String) checkRead} method
* denies read access to the file.
*/
List<AclEntry> getAcl() throws IOException;
/**
* Updates (replace) the access control list.
*
* <p> Where the file system supports Access Control Lists, and it uses an
* ACL model that differs from the NFSv4 defined ACL model, then this method
* must translate the ACL to the model supported by the file system. This
* method should reject (by throwing {@link IOException IOException}) any
* attempt to write an ACL that would appear to make the file more secure
* than would be the case if the ACL were updated. Where an implementation
* does not support a mapping of {@link AclEntryType#AUDIT} or {@link
* AclEntryType#ALARM} entries, then this method ignores these entries when
* writing the ACL.
*
* <p> If an ACL entry contains a {@link AclEntry#principal user-principal}
* that is not associated with the same provider as this attribute view then
* {@link ProviderMismatchException} is thrown. Additional validation, if
* any, is implementation dependent.
*
* <p> If the file system supports other security related file attributes
* (such as a file {@link PosixFileAttributes#permissions
* access-permissions} for example), the updating the access control list
* may also cause these security related attributes to be updated.
*
* @param acl
* The new access control list
*
* @throws IOException
* If an I/O error occurs or the ACL is invalid
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt>
* or its {@link SecurityManager#checkWrite(String) checkWrite}
* method denies write access to the file.
*/
void setAcl(List<AclEntry> acl) throws IOException;
}

118
jdk/src/share/classes/java/nio/file/attribute/AttributeView.java Normal file
View file

@ -0,0 +1,118 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file.attribute;
import java.util.*;
import java.io.IOException;
/**
* An object that provides a read-only or updatable <em>view</em> of non-opaque
* values associated with an object in a filesystem. This interface is extended
* or implemented by specific attribute views that define the attributes
* supported by the view. A specific attribute view will typically define
* type-safe methods to read or update the attributes that it supports. It also
* provides <em>dynamic access</em> where the {@link #readAttributes
* readAttributes}, {@link #getAttribute getAttribute} and {@link #setAttribute
* setAttributs} methods are used to access the attributes by names defined
* by the attribute view. Implementations must ensure that the attribute names
* do not contain the colon (':') or comma (',') characters.
*
* @since 1.7
*/
public interface AttributeView {
/**
* Returns the name of the attribute view.
*/
String name();
/**
* Reads the value of an attribute.
*
* @param attribute
* The attribute name (case sensitive)
*
* @return The value of the attribute, or {@code null} if the attribute is
* not supported
*
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* If a security manager is set and it denies access
*/
Object getAttribute(String attribute) throws IOException;
/**
* Sets/updates the value of an attribute.
*
* @param attribute
* The attribute name (case sensitive)
* @param value
* The attribute value
*
* @throws UnsupportedOperationException
* If the attribute is not supported or this attribute view does
* not support updating the value of the attribute
* @throws IllegalArgumentException
* If the attribute value is of the correct type but has an
* inappropriate value
* @throws ClassCastException
* If the attribute value is not of the expected type or is a
* collection containing elements that are not of the expected
* type
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* If a security manager is set and it denies access
*/
void setAttribute(String attribute, Object value) throws IOException;
/**
* Reads all, or a subset, of the attributes supported by this file attribute
* view.
*
* <p> The {@code first} and {@code rest} parameters are the names of the
* attributes to read. If any of the parameters has the value {@code "*"}
* then all attributes are read. Attributes that are not supported are
* ignored and will not be present in the returned map. It is implementation
* specific if all attributes are read as an atomic operation with respect
* to other file system operations.
*
* @param first
* The name of an attribute to read (case sensitive)
* @param rest
* The names of others attributes to read (case sensitive)
*
* @return An unmodifiable map of the attributes; may be empty. Its keys are
* the attribute names, its values are the attribute values
*
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* If a security manager is set and it denies access
*/
Map<String,?> readAttributes(String first, String... rest) throws IOException;
}

703
jdk/src/share/classes/java/nio/file/attribute/Attributes.java Normal file
View file

@ -0,0 +1,703 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file.attribute;
import java.nio.file.*;
import java.io.IOException;
import java.util.*;
import java.util.concurrent.TimeUnit;
/**
* This class consists exclusively of static methods that operate on or return
* the attributes of files or file stores. These methods provide for convenient
* use of the {@link AttributeView attribute-views} defined in this package.
*
* @since 1.7
*/
public final class Attributes {
private Attributes() {
}
/**
* Splits the given attribute name into the name of an attribute view and
* the attribute. If the attribute view is not identified then it assumed
* to be "basic".
*/
private static String[] split(String attribute) {
String[] s = new String[2];
int pos = attribute.indexOf(':');
if (pos == -1) {
s[0] = "basic";
s[1] = attribute;
} else {
s[0] = attribute.substring(0, pos++);
s[1] = (pos == attribute.length()) ? "" : attribute.substring(pos);
}
return s;
}
/**
* Sets the value of a file attribute.
*
* <p> The {@code attribute} parameter identifies the attribute to be set
* and takes the form:
* <blockquote>
* [<i>view-name</i><b>:</b>]<i>attribute-name</i>
* </blockquote>
* where square brackets [...] delineate an optional component and the
* character {@code ':'} stands for itself.
*
* <p> <i>view-name</i> is the {@link FileAttributeView#name name} of a {@link
* FileAttributeView} that identifies a set of file attributes. If not
* specified then it defaults to {@code "basic"}, the name of the file
* attribute view that identifies the basic set of file attributes common to
* many file systems. <i>attribute-name</i> is the name of the attribute
* within the set.
*
* <p> <b>Usage Example:</b>
* Suppose we want to set the DOS "hidden" attribute:
* <pre>
* Attributes.setAttribute(file, "dos:hidden", true);
* </pre>
*
* @param file
* A file reference that locates the file
* @param attribute
* The attribute to set
* @param value
* The attribute value
*
* @throws UnsupportedOperationException
* If the attribute view is not available or it does not
* support updating the attribute
* @throws IllegalArgumentException
* If the attribute value is of the correct type but has an
* inappropriate value
* @throws ClassCastException
* If the attribute value is not of the expected type or is a
* collection containing elements that are not of the expected
* type
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, its {@link SecurityManager#checkWrite(String) checkWrite}
* method denies write access to the file. If this method is invoked
* to set security sensitive attributes then the security manager
* may be invoked to check for additional permissions.
*/
public static void setAttribute(FileRef file, String attribute, Object value)
throws IOException
{
String[] s = split(attribute);
FileAttributeView view = file.getFileAttributeView(s[0]);
if (view == null)
throw new UnsupportedOperationException("View '" + s[0] + "' not available");
view.setAttribute(s[1], value);
}
/**
* Reads the value of a file attribute.
*
* <p> The {@code attribute} parameter identifies the attribute to be read
* and takes the form:
* <blockquote>
* [<i>view-name</i><b>:</b>]<i>attribute-name</i>
* </blockquote>
* where square brackets [...] delineate an optional component and the
* character {@code ':'} stands for itself.
*
* <p> <i>view-name</i> is the {@link FileAttributeView#name name} of a {@link
* FileAttributeView} that identifies a set of file attributes. If not
* specified then it defaults to {@code "basic"}, the name of the file
* attribute view that identifies the basic set of file attributes common to
* many file systems. <i>attribute-name</i> is the name of the attribute.
*
* <p> The {@code options} array may be used to indicate how symbolic links
* are handled for the case that the file is a symbolic link. By default,
* symbolic links are followed and the file attribute of the final target
* of the link is read. If the option {@link LinkOption#NOFOLLOW_LINKS
* NOFOLLOW_LINKS} is present then symbolic links are not followed and so
* the method returns the file attribute of the symbolic link.
*
* <p> <b>Usage Example:</b>
* Suppose we require the user ID of the file owner on a system that
* supports a "{@code unix}" view:
* <pre>
* int uid = (Integer)Attributes.getAttribute(file, "unix:uid");
* </pre>
*
* @param file
* A file reference that locates the file
* @param attribute
* The attribute to read
* @param options
* Options indicating how symbolic links are handled
*
* @return The attribute value, or {@code null} if the attribute view
* is not available or it does not support reading the attribute
*
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, its {@link SecurityManager#checkRead(String) checkRead}
* method denies read access to the file. If this method is invoked
* to read security sensitive attributes then the security manager
* may be invoked to check for additional permissions.
*/
public static Object getAttribute(FileRef file,
String attribute,
LinkOption... options)
throws IOException
{
String[] s = split(attribute);
FileAttributeView view = file.getFileAttributeView(s[0], options);
if (view != null)
return view.getAttribute(s[1]);
// view not available
return null;
}
/**
* Reads a set of file attributes as a bulk operation.
*
* <p> The {@code attributes} parameter identifies the attributes to be read
* and takes the form:
* <blockquote>
* [<i>view-name</i><b>:</b>]<i>attribute-list</i>
* </blockquote>
* where square brackets [...] delineate an optional component and the
* character {@code ':'} stands for itself.
*
* <p> <i>view-name</i> is the {@link FileAttributeView#name name} of a {@link
* FileAttributeView} that identifies a set of file attributes. If not
* specified then it defaults to {@code "basic"}, the name of the file
* attribute view that identifies the basic set of file attributes common to
* many file systems.
*
* <p> The <i>attribute-list</i> component is a comma separated list of
* zero or more names of attributes to read. If the list contains the value
* {@code "*"} then all attributes are read. Attributes that are not supported
* are ignored and will not be present in the returned map. It is
* implementation specific if all attributes are read as an atomic operation
* with respect to other file system operations.
*
* <p> The following examples demonstrate possible values for the {@code
* attributes} parameter:
*
* <blockquote>
* <table border="0">
* <tr>
* <td> {@code "*"} </td>
* <td> Read all {@link BasicFileAttributes basic-file-attributes}. </td>
* </tr>
* <tr>
* <td> {@code "size,lastModifiedTime,lastAccessTime"} </td>
* <td> Reads the file size, last modified time, and last access time
* attributes. </td>
* </tr>
* <tr>
* <td> {@code "posix:*"} </td>
* <td> Read all {@link PosixFileAttributes POSIX-file-attributes}.. </td>
* </tr>
* <tr>
* <td> {@code "posix:permissions,owner,size"} </td>
* <td> Reads the POSX file permissions, owner, and file size. </td>
* </tr>
* </table>
* </blockquote>
*
* <p> The {@code options} array may be used to indicate how symbolic links
* are handled for the case that the file is a symbolic link. By default,
* symbolic links are followed and the file attributes of the final target
* of the link are read. If the option {@link LinkOption#NOFOLLOW_LINKS
* NOFOLLOW_LINKS} is present then symbolic links are not followed and so
* the method returns the file attributes of the symbolic link.
*
* @param file
* A file reference that locates the file
* @param attributes
* The attributes to read
* @param options
* Options indicating how symbolic links are handled
*
* @return A map of the attributes returned; may be empty. The map's keys
* are the attribute names, its values are the attribute values
*
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, its {@link SecurityManager#checkRead(String) checkRead}
* method denies read access to the file. If this method is invoked
* to read security sensitive attributes then the security manager
* may be invoke to check for additional permissions.
*/
public static Map<String,?> readAttributes(FileRef file,
String attributes,
LinkOption... options)
throws IOException
{
String[] s = split(attributes);
FileAttributeView view = file.getFileAttributeView(s[0], options);
if (view != null) {
// further split attributes into the first and rest.
String[] names = s[1].split(",");
int rem = names.length-1;
String first = names[0];
String[] rest = new String[rem];
if (rem > 0) System.arraycopy(names, 1, rest, 0, rem);
return view.readAttributes(first, rest);
}
// view not available
return Collections.emptyMap();
}
/**
* Reads the basic file attributes of a file.
*
* <p> The {@code options} array may be used to indicate how symbolic links
* are handled for the case that the file is a symbolic link. By default,
* symbolic links are followed and the file attributes of the final target
* of the link are read. If the option {@link LinkOption#NOFOLLOW_LINKS
* NOFOLLOW_LINKS} is present then symbolic links are not followed and so
* the method returns the file attributes of the symbolic link. This option
* should be used where there is a need to determine if a file is a
* symbolic link:
* <pre>
* boolean isSymbolicLink = Attributes.readBasicFileAttributes(file, NOFOLLOW_LINKS).isSymbolicLink();
* </pre>
*
* <p> It is implementation specific if all file attributes are read as an
* atomic operation with respect to other file system operations.
*
* @param file
* A file reference that locates the file
* @param options
* Options indicating how symbolic links are handled
*
* @return The basic file attributes
*
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, the security manager's {@link
* SecurityManager#checkRead(String) checkRead} method is invoked
* to check read access to file
*
* @see BasicFileAttributeView#readAttributes
*/
public static BasicFileAttributes readBasicFileAttributes(FileRef file,
LinkOption... options)
throws IOException
{
return file.getFileAttributeView(BasicFileAttributeView.class, options)
.readAttributes();
}
/**
* Reads the POSIX file attributes of a file.
*
* <p> The {@code file} parameter locates a file that supports the {@link
* PosixFileAttributeView}. This file attribute view provides access to a
* subset of the file attributes commonly associated with files on file
* systems used by operating systems that implement the Portable Operating
* System Interface (POSIX) family of standards. It is implementation
* specific if all file attributes are read as an atomic operation with
* respect to other file system operations.
*
* <p> The {@code options} array may be used to indicate how symbolic links
* are handled for the case that the file is a symbolic link. By default,
* symbolic links are followed and the file attributes of the final target
* of the link are read. If the option {@link LinkOption#NOFOLLOW_LINKS
* NOFOLLOW_LINKS} is present then symbolic links are not followed and so
* the method returns the file attributes of the symbolic link.
*
* @param file
* A file reference that locates the file
* @param options
* Options indicating how symbolic links are handled
*
* @return The POSIX file attributes
*
* @throws UnsupportedOperationException
* If the {@code PosixFileAttributeView} is not available
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt>
* or its {@link SecurityManager#checkRead(String) checkRead} method
* denies read access to the file.
*
* @see PosixFileAttributeView#readAttributes
*/
public static PosixFileAttributes readPosixFileAttributes(FileRef file,
LinkOption... options)
throws IOException
{
PosixFileAttributeView view =
file.getFileAttributeView(PosixFileAttributeView.class, options);
if (view == null)
throw new UnsupportedOperationException();
return view.readAttributes();
}
/**
* Reads the DOS file attributes of a file.
*
* <p> The {@code file} parameter locates a file that supports the {@link
* DosFileAttributeView}. This file attribute view provides access to
* legacy "DOS" attributes supported by the file systems such as File
* Allocation Table (FAT), commonly used in <em>consumer devices</em>. It is
* implementation specific if all file attributes are read as an atomic
* operation with respect to other file system operations.
*
* <p> The {@code options} array may be used to indicate how symbolic links
* are handled for the case that the file is a symbolic link. By default,
* symbolic links are followed and the file attributes of the final target
* of the link are read. If the option {@link LinkOption#NOFOLLOW_LINKS
* NOFOLLOW_LINKS} is present then symbolic links are not followed and so
* the method returns the file attributes of the symbolic link.
*
* @param file
* A file reference that locates the file
* @param options
* Options indicating how symbolic links are handled
*
* @return The DOS file attributes
*
* @throws UnsupportedOperationException
* If the {@code DosFileAttributeView} is not available
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, the security manager's {@link
* SecurityManager#checkRead(String) checkRead} method is invoked
* to check read access to file
*
* @see DosFileAttributeView#readAttributes
*/
public static DosFileAttributes readDosFileAttributes(FileRef file,
LinkOption... options)
throws IOException
{
DosFileAttributeView view =
file.getFileAttributeView(DosFileAttributeView.class, options);
if (view == null)
throw new UnsupportedOperationException();
return view.readAttributes();
}
/**
* Returns the owner of a file.
*
* <p> The {@code file} parameter locates a file that supports the {@link
* FileOwnerAttributeView}. This file attribute view provides access to
* a file attribute that is the owner of the file.
*
* @param file
* A file reference that locates the file
*
* @return A user principal representing the owner of the file
*
* @throws UnsupportedOperationException
* If the {@code FileOwnerAttributeView} is not available
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt>
* or its {@link SecurityManager#checkRead(String) checkRead} method
* denies read access to the file.
*
* @see FileOwnerAttributeView#getOwner
*/
public static UserPrincipal getOwner(FileRef file) throws IOException {
FileOwnerAttributeView view =
file.getFileAttributeView(FileOwnerAttributeView.class);
if (view == null)
throw new UnsupportedOperationException();
return view.getOwner();
}
/**
* Updates the file owner.
*
* <p> The {@code file} parameter locates a file that supports the {@link
* FileOwnerAttributeView}. This file attribute view provides access to
* a file attribute that is the owner of the file.
*
* @param file
* A file reference that locates the file
* @param owner
* The new file owner
*
* @throws UnsupportedOperationException
* If the {@code FileOwnerAttributeView} is not available
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt>
* or its {@link SecurityManager#checkWrite(String) checkWrite}
* method denies write access to the file.
*
* @see FileOwnerAttributeView#setOwner
*/
public static void setOwner(FileRef file, UserPrincipal owner)
throws IOException
{
FileOwnerAttributeView view =
file.getFileAttributeView(FileOwnerAttributeView.class);
if (view == null)
throw new UnsupportedOperationException();
view.setOwner(owner);
}
/**
* Reads a file's Access Control List (ACL).
*
* <p> The {@code file} parameter locates a file that supports the {@link
* AclFileAttributeView}. This file attribute view provides access to ACLs
* based on the ACL model specified in
* <a href="http://www.ietf.org/rfc/rfc3530.txt"><i>RFC&nbsp;3530</i></a>.
*
* @param file
* A file reference that locates the file
*
* @return An ordered list of {@link AclEntry entries} representing the
* ACL. The returned list is modifiable.
*
* @throws UnsupportedOperationException
* If the {@code AclAttributeView} is not available
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt>
* or its {@link SecurityManager#checkRead(String) checkRead} method
* denies read access to the file.
*
* @see AclFileAttributeView#getAcl
*/
public static List<AclEntry> getAcl(FileRef file) throws IOException {
AclFileAttributeView view =
file.getFileAttributeView(AclFileAttributeView.class);
if (view == null)
throw new UnsupportedOperationException();
return view.getAcl();
}
/**
* Updates a file's Access Control List (ACL).
*
* <p> The {@code file} parameter locates a file that supports the {@link
* AclFileAttributeView}. This file attribute view provides access to ACLs
* based on the ACL model specified in
* <a href="http://www.ietf.org/rfc/rfc3530.txt"><i>RFC&nbsp;3530</i></a>.
*
* @param file
* A file reference that locates the file
* @param acl
* The new file ACL
*
* @throws UnsupportedOperationException
* If the {@code AclFileAttributeView} is not available
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt>
* or its {@link SecurityManager#checkWrite(String) checkWrite}
* method denies write access to the file.
*
* @see AclFileAttributeView#setAcl
*/
public static void setAcl(FileRef file, List<AclEntry> acl)
throws IOException
{
AclFileAttributeView view =
file.getFileAttributeView(AclFileAttributeView.class);
if (view == null)
throw new UnsupportedOperationException();
view.setAcl(acl);
}
/**
* Updates the value of a file's last modified time attribute.
*
* <p> The time value is measured since the epoch
* (00:00:00 GMT, January 1, 1970) and is converted to the precision supported
* by the file system. Converting from finer to coarser granularities result
* in precision loss.
*
* <p> If the file system does not support a last modified time attribute then
* this method has no effect.
*
* @param file
* A file reference that locates the file
*
* @param lastModifiedTime
* The new last modified time, or {@code -1L} to update it to
* the current time
* @param unit
* A {@code TimeUnit} determining how to interpret the
* {@code lastModifiedTime} parameter
*
* @throws IllegalArgumentException
* If the {@code lastModifiedime} parameter is a negative value other
* than {@code -1L}
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, the security manager's {@link
* SecurityManager#checkWrite(String) checkWrite} method is invoked
* to check write access to file
*
* @see BasicFileAttributeView#setTimes
*/
public static void setLastModifiedTime(FileRef file,
long lastModifiedTime,
TimeUnit unit)
throws IOException
{
file.getFileAttributeView(BasicFileAttributeView.class)
.setTimes(lastModifiedTime, null, null, unit);
}
/**
* Updates the value of a file's last access time attribute.
*
* <p> The time value is measured since the epoch
* (00:00:00 GMT, January 1, 1970) and is converted to the precision supported
* by the file system. Converting from finer to coarser granularities result
* in precision loss.
*
* <p> If the file system does not support a last access time attribute then
* this method has no effect.
*
* @param lastAccessTime
* The new last access time, or {@code -1L} to update it to
* the current time
* @param unit
* A {@code TimeUnit} determining how to interpret the
* {@code lastModifiedTime} parameter
*
* @throws IllegalArgumentException
* If the {@code lastAccessTime} parameter is a negative value other
* than {@code -1L}
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, the security manager's {@link
* SecurityManager#checkWrite(String) checkWrite} method is invoked
* to check write access to file
*
* @see BasicFileAttributeView#setTimes
*/
public static void setLastAccessTime(FileRef file,
long lastAccessTime,
TimeUnit unit)
throws IOException
{
file.getFileAttributeView(BasicFileAttributeView.class)
.setTimes(null, lastAccessTime, null, unit);
}
/**
* Sets a file's POSIX permissions.
*
* <p> The {@code file} parameter is a reference to an existing file. It
* supports the {@link PosixFileAttributeView} that provides access to file
* attributes commonly associated with files on file systems used by
* operating systems that implement the Portable Operating System Interface
* (POSIX) family of standards.
*
* @param file
* A file reference that locates the file
* @param perms
* The new set of permissions
*
* @throws UnsupportedOperationException
* If {@code PosixFileAttributeView} is not available
* @throws ClassCastException
* If the sets contains elements that are not of type {@code
* PosixFilePermission}
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, and a security manager is
* installed, it denies {@link RuntimePermission}<tt>("accessUserInformation")</tt>
* or its {@link SecurityManager#checkWrite(String) checkWrite}
* method denies write access to the file.
*
* @see PosixFileAttributeView#setPermissions
*/
public static void setPosixFilePermissions(FileRef file,
Set<PosixFilePermission> perms)
throws IOException
{
PosixFileAttributeView view =
file.getFileAttributeView(PosixFileAttributeView.class);
if (view == null)
throw new UnsupportedOperationException();
view.setPermissions(perms);
}
/**
* Reads the space attributes of a file store.
*
* <p> The {@code store} parameter is a file store that supports the
* {@link FileStoreSpaceAttributeView} providing access to the space related
* attributes of the file store. It is implementation specific if all attributes
* are read as an atomic operation with respect to other file system operations.
*
* @param store
* The file store
*
* @return The file store space attributes
*
* @throws UnsupportedOperationException
* If the file store space attribute view is not supported
* @throws IOException
* If an I/O error occurs
*
* @see FileStoreSpaceAttributeView#readAttributes()
*/
public static FileStoreSpaceAttributes readFileStoreSpaceAttributes(FileStore store)
throws IOException
{
FileStoreSpaceAttributeView view =
store.getFileStoreAttributeView(FileStoreSpaceAttributeView.class);
if (view == null)
throw new UnsupportedOperationException();
return view.readAttributes();
}
}

186
jdk/src/share/classes/java/nio/file/attribute/BasicFileAttributeView.java Normal file
View file

@ -0,0 +1,186 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file.attribute;
import java.util.concurrent.TimeUnit;
import java.io.IOException;
/**
* A file attribute view that provides a view of a <em>basic set</em> of file
* attributes common to many file systems. The basic set of file attributes
* consist of <em>mandatory</em> and <em>optional</em> file attributes as
* defined by the {@link BasicFileAttributes} interface.
* <p> The file attributes are retrieved from the file system as a <em>bulk
* operation</em> by invoking the {@link #readAttributes() readAttributes} method.
* This class also defines the {@link #setTimes setTimes} method to update the
* file's time attributes.
*
* <p> Where dynamic access to file attributes is required, the attributes
* supported by this attribute view have the following names and types:
* <blockquote>
* <table border="1" cellpadding="8">
* <tr>
* <th> Name </th>
* <th> Type </th>
* </tr>
* <tr>
* <td> "lastModifiedTime" </td>
* <td> {@link Long} </td>
* </tr>
* <tr>
* <td> "lastAccessTime" </td>
* <td> {@link Long} </td>
* </tr>
* <tr>
* <td> "creationTime" </td>
* <td> {@link Long} </td>
* </tr>
* <tr>
* <td> "resolution" </td>
* <td> {@link java.util.concurrent.TimeUnit} </td>
* </tr>
* <tr>
* <td> "size" </td>
* <td> {@link Long} </td>
* </tr>
* <tr>
* <td> "isRegularFile" </td>
* <td> {@link Boolean} </td>
* </tr>
* <tr>
* <td> "isDirectory" </td>
* <td> {@link Boolean} </td>
* </tr>
* <tr>
* <td> "isSymbolicLink" </td>
* <td> {@link Boolean} </td>
* </tr>
* <tr>
* <td> "isOther" </td>
* <td> {@link Boolean} </td>
* </tr>
* <tr>
* <td> "linkCount" </td>
* <td> {@link Integer} </td>
* </tr>
* <tr>
* <td> "fileKey" </td>
* <td> {@link Object} </td>
* </tr>
* </table>
* </blockquote>
*
* <p> The {@link #getAttribute getAttribute} or {@link
* #readAttributes(String,String[]) readAttributes(String,String[])} methods may
* be used to read any of these attributes as if by invoking the {@link
* #readAttributes() readAttributes()} method.
*
* <p> The {@link #setAttribute setAttribute} method may be used to update the
* file's last modified time, last access time or create time attributes as if
* by invoking the {@link #setTimes setTimes} method. In that case, the time
* value is interpreted in {@link TimeUnit#MILLISECONDS milliseconds} and
* converted to the precision supported by the file system.
*
* @since 1.7
* @see Attributes
*/
public interface BasicFileAttributeView
extends FileAttributeView
{
/**
* Returns the name of the attribute view. Attribute views of this type
* have the name {@code "basic"}.
*/
@Override
String name();
/**
* Reads the basic file attributes as a bulk operation.
*
* <p> It is implementation specific if all file attributes are read as an
* atomic operation with respect to other file system operations.
*
* @return The file attributes
*
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, its {@link SecurityManager#checkRead(String) checkRead}
* method is invoked to check read access to the file
*/
BasicFileAttributes readAttributes() throws IOException;
/**
* Updates any or all of the file's last modified time, last access time,
* and create time attributes.
*
* <p> This method updates the file's timestamp attributes. The values are
* measured since the epoch (00:00:00 GMT, January 1, 1970) and converted to
* the precision supported by the file system. Converting from finer to
* coarser granularities result in precision loss. If a value is larger
* than the maximum supported by the file system then the corresponding
* timestamp is set to its maximum value.
*
* <p> If any of the {@code lastModifiedTime}, {@code lastAccessTime},
* or {@code createTime} parameters has the value {@code null} then the
* corresponding timestamp is not changed. An implementation may require to
* read the existing values of the file attributes when only some, but not
* all, of the timestamp attributes are updated. Consequently, this method
* may not be an atomic operation with respect to other file system
* operations. If all of the {@code lastModifiedTime}, {@code
* lastAccessTime} and {@code createTime} parameters are {@code null} then
* this method has no effect.
*
* @param lastModifiedTime
* The new last modified time, or {@code -1L} to update it to
* the current time, or {@code null} to not change the attribute
* @param lastAccessTime
* The last access time, or {@code -1L} to update it to
* the current time, or {@code null} to not change the attribute.
* @param createTime
* The file's create time, or {@code -1L} to update it to
* the current time, or {@code null} to not change the attribute
* @param unit
* A {@code TimeUnit} determining how to interpret the time values
*
* @throws IllegalArgumentException
* If any of the parameters is a negative value other than {@code
* -1L}
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default provider, a security manager is
* installed, its {@link SecurityManager#checkWrite(String) checkWrite}
* method is invoked to check write access to the file
*/
void setTimes(Long lastModifiedTime,
Long lastAccessTime,
Long createTime,
TimeUnit unit) throws IOException;
}

163
jdk/src/share/classes/java/nio/file/attribute/BasicFileAttributes.java Normal file
View file

@ -0,0 +1,163 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file.attribute;
import java.util.concurrent.TimeUnit;
/**
* Basic attributes associated with a file in a file system.
*
* <p> Basic file attributes are attributes that are common to many file systems
* and consist of mandatory and optional file attributes as defined by this
* interface.
*
* <p> <b>Usage Example:</b>
* <pre>
* FileRef file = ...
* BasicFileAttributes attrs = Attributes.readBasicFileAttributes(file);
* </pre>
*
* @since 1.7
*
* @see BasicFileAttributeView
*/
public interface BasicFileAttributes {
/**
* Returns the time of last modification.
*
* <p> The {@link #resolution() resolution} method returns the {@link TimeUnit}
* to interpret the return value of this method.
*
* @return A <code>long</code> value representing the time the file was
* last modified since the epoch (00:00:00 GMT, January 1, 1970),
* or {@code -1L} if the attribute is not supported.
*/
long lastModifiedTime();
/**
* Returns the time of last access if supported.
*
* <p> The {@link #resolution() resolution} method returns the {@link TimeUnit}
* to interpret the return value of this method.
*
* @return A <code>long</code> value representing the time of last access
* since the epoch (00:00:00 GMT, January 1, 1970), or {@code -1L}
* if the attribute is not supported.
*/
long lastAccessTime();
/**
* Returns the creation time if supported. The creation time is the time
* that the file was created.
*
* <p> The {@link #resolution() resolution} method returns the {@link TimeUnit}
* to interpret the return value of this method.
*
* @return A <code>long</code> value representing the time the file was
* created since the epoch (00:00:00 GMT, January 1, 1970), or
* {@code -1L} if the attribute is not supported.
*/
long creationTime();
/**
* Returns the {@link TimeUnit} required to interpret the time of last
* modification, time of last access, and creation time.
*
* @return The {@code TimeUnit} required to interpret the file time stamps
*/
TimeUnit resolution();
/**
* Tells whether the file is a regular file with opaque content.
*/
boolean isRegularFile();
/**
* Tells whether the file is a directory.
*/
boolean isDirectory();
/**
* Tells whether the file is a symbolic-link.
*/
boolean isSymbolicLink();
/**
* Tells whether the file is something other than a regular file, directory,
* or link.
*/
boolean isOther();
/**
* Returns the size of the file (in bytes). The size may differ from the
* actual size on the file system due to compression, support for sparse
* files, or other reasons. The size of files that are not {@link
* #isRegularFile regular} files is implementation specific and
* therefore unspecified.
*
* @return The file size, in bytes
*/
long size();
/**
* Returns the number of <em>links</em> to this file.
*
* <p> On file systems where the same file may be in several directories then
* the link count is the number of directory entries for the file. The return
* value is {@code 1} on file systems that only allow a file to have a
* single name in a single directory.
*
* @see java.nio.file.Path#createLink
*/
int linkCount();
/**
* Returns an object that uniquely identifies the given file, or {@code
* null} if a file key is not available. On some platforms or file systems
* it is possible to use an identifier, or a combination of identifiers to
* uniquely identify a file. Such identifiers are important for operations
* such as file tree traversal in file systems that support <a
* href="../package-summary.html#links">symbolic links</a> or file systems
* that allow a file to be an entry in more than one directory. On UNIX file
* systems, for example, the <em>device ID</em> and <em>inode</em> are
* commonly used for such purposes.
*
* <p> The file key returned by this method can only be guaranteed to be
* unique if the file system and files remain static. Whether a file system
* re-uses identifiers after a file is deleted is implementation dependent and
* therefore unspecified.
*
* <p> File keys returned by this method can be compared for equality and are
* suitable for use in collections. If the file system and files remain static,
* and two files are the {@link java.nio.file.FileRef#isSameFile same} with
* non-{@code null} file keys, then their file keys are equal.
*
* @see java.nio.file.Files#walkFileTree
*/
Object fileKey();
}

179
jdk/src/share/classes/java/nio/file/attribute/DosFileAttributeView.java Normal file
View file

@ -0,0 +1,179 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file.attribute;
import java.io.IOException;
/**
* A file attribute view that provides a view of the legacy "DOS" file attributes.
* These attributes are supported by file systems such as the File Allocation
* Table (FAT) format commonly used in <em>consumer devices</em>.
*
* <p> A {@code DosFileAttributeView} is a {@link BasicFileAttributeView} that
* additionally supports access to the set of DOS attribute flags that are used
* to indicate if the file is read-only, hidden, a system file, or archived.
*
* <p> Where dynamic access to file attributes is required, the attributes
* supported by this attribute view are as defined by {@code
* BasicFileAttributeView}, and in addition, the following attributes are
* supported:
* <blockquote>
* <table border="1" cellpadding="8">
* <tr>
* <th> Name </th>
* <th> Type </th>
* </tr>
* <tr>
* <td> readonly </td>
* <td> {@link Boolean} </td>
* </tr>
* <tr>
* <td> hidden </td>
* <td> {@link Boolean} </td>
* </tr>
* <tr>
* <td> system </td>
* <td> {@link Boolean} </td>
* </tr>
* <tr>
* <td> archive </td>
* <td> {@link Boolean} </td>
* </tr>
* </table>
* </blockquote>
*
* <p> The {@link #getAttribute getAttribute} or {@link #readAttributes(String,String[])
* readAttributes(String,String[])} methods may be used to read any of these
* attributes, or any of the attributes defined by {@link BasicFileAttributeView}
* as if by invoking the {@link #readAttributes readAttributes()} method.
*
* <p> The {@link #setAttribute setAttribute} method may be used to update the
* file's last modified time, last access time or create time attributes as
* defined by {@link BasicFileAttributeView}. It may also be used to update
* the DOS attributes as if by invoking the {@link #setReadOnly setReadOnly},
* {@link #setHidden setHidden}, {@link #setSystem setSystem}, and {@link
* #setArchive setArchive} methods respectively.
*
* @since 1.7
*/
public interface DosFileAttributeView
extends BasicFileAttributeView
{
/**
* Returns the name of the attribute view. Attribute views of this type
* have the name {@code "dos"}.
*/
@Override
String name();
/**
* @throws IOException {@inheritDoc}
* @throws SecurityException {@inheritDoc}
*/
@Override
DosFileAttributes readAttributes() throws IOException;
/**
* Updates the value of the read-only attribute.
*
* <p> It is implementation specific if the attribute can be updated as an
* atomic operation with respect to other file system operations. An
* implementation may, for example, require to read the existing value of
* the DOS attribute in order to update this attribute.
*
* @param value
* The new value of the attribute
*
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default, and a security manager is installed,
* its {@link SecurityManager#checkWrite(String) checkWrite} method
* is invoked to check write access to the file
*/
void setReadOnly(boolean value) throws IOException;
/**
* Updates the value of the hidden attribute.
*
* <p> It is implementation specific if the attribute can be updated as an
* atomic operation with respect to other file system operations. An
* implementation may, for example, require to read the existing value of
* the DOS attribute in order to update this attribute.
*
* @param value
* The new value of the attribute
*
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default, and a security manager is installed,
* its {@link SecurityManager#checkWrite(String) checkWrite} method
* is invoked to check write access to the file
*/
void setHidden(boolean value) throws IOException;
/**
* Updates the value of the system attribute.
*
* <p> It is implementation specific if the attribute can be updated as an
* atomic operation with respect to other file system operations. An
* implementation may, for example, require to read the existing value of
* the DOS attribute in order to update this attribute.
*
* @param value
* The new value of the attribute
*
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default, and a security manager is installed,
* its {@link SecurityManager#checkWrite(String) checkWrite} method
* is invoked to check write access to the file
*/
void setSystem(boolean value) throws IOException;
/**
* Updates the value of the archive attribute.
*
* <p> It is implementation specific if the attribute can be updated as an
* atomic operation with respect to other file system operations. An
* implementation may, for example, require to read the existing value of
* the DOS attribute in order to update this attribute.
*
* @param value
* The new value of the attribute
*
* @throws IOException
* If an I/O error occurs
* @throws SecurityException
* In the case of the default, and a security manager is installed,
* its {@link SecurityManager#checkWrite(String) checkWrite} method
* is invoked to check write access to the file
*/
void setArchive(boolean value) throws IOException;
}

84
jdk/src/share/classes/java/nio/file/attribute/DosFileAttributes.java Normal file
View file

@ -0,0 +1,84 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file.attribute;
/**
* File attributes associated with a file in a file system that supports
* legacy "DOS" attributes.
*
* <p> The DOS attributes of a file are retrieved using a {@link
* DosFileAttributeView} by invoking its {@link DosFileAttributeView#readAttributes
* readAttributes} method.
*
* @since 1.7
*
* @see Attributes#readDosFileAttributes
*/
public interface DosFileAttributes
extends BasicFileAttributes
{
/**
* Returns the value of the read-only attribute.
*
* <p> This attribute is often used as a simple access control mechanism
* to prevent files from being deleted or updated. Whether the file system
* or platform does any enforcement to prevent <em>read-only</em> files
* from being updated is implementation specific.
*
* @return The value of the read-only attribute.
*/
boolean isReadOnly();
/**
* Returns the value of the hidden attribute.
*
* <p> This attribute is often used to indicate if the file is visible to
* users.
*
* @return The value of the hidden attribute.
*/
boolean isHidden();
/**
* Returns the value of the archive attribute.
*
* <p> This attribute is typically used by backup programs.
*
* @return The value of the archive attribute.
*/
boolean isArchive();
/**
* Returns the value of the system attribute.
*
* <p> This attribute is often used to indicate that the file is a component
* of the operating system.
*
* @return The value of the system attribute.
*/
boolean isSystem();
}

50
jdk/src/share/classes/java/nio/file/attribute/FileAttribute.java Normal file
View file

@ -0,0 +1,50 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file.attribute;
/**
* An object that encapsulates the value of a file attribute that can be set
* atomically when creating a new file or directory by invoking the {@link
* java.nio.file.Path#createFile createFile} or {@link
* java.nio.file.Path#createDirectory createDirectory} methods.
*
* @param <T> The type of the file attribute value
*
* @since 1.7
* @see PosixFilePermissions#asFileAttribute
*/
public interface FileAttribute<T> {
/**
* Returns the attribute name.
*/
String name();
/**
* Returns the attribute value.
*/
T value();
}

43
jdk/src/share/classes/java/nio/file/attribute/FileAttributeView.java Normal file
View file

@ -0,0 +1,43 @@
/*
* Copyright 2007-2009 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*/
package java.nio.file.attribute;
/**
* An attribute view that is a read-only or updatable view of non-opaque
* values associated with a file in a filesystem. This interface is extended or
* implemented by specific file attribute views that define methods to read
* and/or update the attributes of a file.
*
* @since 1.7
*
* @see java.nio.file.FileRef#getFileAttributeView(Class,java.nio.file.LinkOption[])
* @see java.nio.file.FileRef#getFileAttributeView(String,java.nio.file.LinkOption[])
*/
public interface FileAttributeView
extends AttributeView
{
}

Some files were not shown because too many files have changed in this diff Show more