com.github.robtimus.filesystems.attribute

Class FileAttributeSupport

java.lang.Object

com.github.robtimus.filesystems.attribute.FileAttributeSupport

public final class FileAttributeSupport
extends Object

A utility class for file attributes.

Reading attributes

Methods of this class can be used to implement FileSystemProvider.readAttributes(Path, String, LinkOption...) as follows, using a FileAttributeViewCollection instance called views:

 @Override
 public Map<String, Object> readAttributes(Path path, String attributes, LinkOption... options) throws IOException {
     String viewName = getViewName(attributes);
     FileAttributeViewMetadata view = views.getView(viewName);
     Set<String> attributeNames = getAttributeNames(attributes, view);

     PosixFileAttributes fileAttributes = readAttributes(path, PosixFileAttributes.class, options);

     Map<String, Object> result = new HashMap<>();
     populateAttributeMap(result, fileAttributes, attributeNames);
     return result;
 }
 

For custom FileAttributeView sub types, the above setup can still be used. Just provide a custom FileAttributeViewMetadata instance, and use populateAttributeMap(Map, String, Set, Supplier) for any custom properties. For instance, where MyFileAttributes extends BasicFileAttributes and has a method myAttribute() that returns the value for a custom attribute:

     MyFileAttributes fileAttributes = readAttributes(path, MyFileAttributes.class, options);

     Map<String, Object> result = new HashMap<>();
     populateAttributeMap(result, fileAttributes, attributeNames); // upcast to BasicFileAttributes
     populateAttributeMap(result, "myAttribute", attributeNames, fileAttributes::myAttribute);
     return result;
 

Setting attributes

Methods of this class can be used to implement FileSystemProvider.setAttribute(Path, String, Object, LinkOption...) as follows, using constants from FileAttributeConstants:

 @Override
 public void setAttribute(Path path, String attribute, Object value, LinkOption... options) throws IOException {
     String viewName = getViewName(attribute);
     String attributeName = getAttributeName(attribute);

     switch (viewName) {
         case BASIC_VIEW:
             BasicFileAttributeView basicView = getFileAttributeView(path, BasicFileAttributeView.class, options);
             FileAttributeSupport.setAttribute(attribute, value, basicView);
             break;
         case FILE_OWNER_VIEW:
             FileOwnerAttributeView fileOwnerView = getFileAttributeView(path, FileOwnerAttributeView.class, options);
             FileAttributeSupport.setAttribute(attribute, value, fileOwnerView);
             break;
         case POSIX_VIEW:
             PosixFileAttributeView posixView = getFileAttributeView(path, PosixFileAttributeView.class, options);
             FileAttributeSupport.setAttribute(attribute, value, posixView);
             break;
         default:
             throw Messages.fileSystemProvider().unsupportedFileAttributeView(viewName);
     }
 }
 

For custom FileAttributeView sub types, the above setup can still be used. Use a switch or if statement to handle your custom attributes, and call any of the setAttribute methods of this class for the default case or else block. For instance, where MyFileAttributeView extends BasicFileAttributeView and has a method setMyAttribute(String value) that sets the value for a custom attribute:

     MyFileAttributeView myView = getFileAttributeView(path, MyFileAttributeView.class, options);
     if ("myAttribute".equals(attributeName)) {
         view.setMyAttribute((String) value);
     } else {
         FileAttributeSupport.setAttribute(attribute, value, myView); // upcast to BasicFileAttributeView
     }
 

Setting attributes during object creation

The toAttributeMap methods of this class can be used to collect FileAttribute objects into maps where the key and value of each entry can be passed to any of the setAttribute methods of this class. This allows file attributes to be set from methods like FileSystemProvider.createDirectory(Path, FileAttribute...) or FileSystemProvider.newByteChannel(Path, Set, FileAttribute...).

Author:

Rob Spoor

Since:

2.2

Method Summary

Modifier and Type	Method and Description
static String	getAttributeName(String attribute) Returns the attribute name from a string representing an attribute to be set for a specific view.
static Set<String>	getAttributeNames(String attributes, FileAttributeViewMetadata view) Returns the actual attribute names from a string representing attributes to read for a specific view.
static String	getViewName(String attributes) Returns the view name from a string representing attributes to read.
static void	populateAttributeMap(Map<String,Object> attributeMap, BasicFileAttributes fileAttributes, Set<String> attributeNames) Populates an attribute map from a BasicFileAttributes object.
static void	populateAttributeMap(Map<String,Object> attributeMap, DosFileAttributes fileAttributes, Set<String> attributeNames) Populates an attribute map from a DosFileAttributes object.
static void	populateAttributeMap(Map<String,Object> attributeMap, PosixFileAttributes fileAttributes, Set<String> attributeNames) Populates an attribute map from a PosixFileAttributes object.
static void	populateAttributeMap(Map<String,Object> attributeMap, String attributeName, Set<String> attributeNames, Supplier<?> getter) Populates an attribute map with a single attribute.
static void	setAttribute(String attributeName, Object value, AclFileAttributeView view) Sets an attribute on an AclFileAttributeView object.
static void	setAttribute(String attributeName, Object value, BasicFileAttributeView view) Sets an attribute on a BasicFileAttributeView object.
static void	setAttribute(String attributeName, Object value, DosFileAttributeView view) Sets an attribute on a DosFileAttributeView object.
static void	setAttribute(String attributeName, Object value, FileOwnerAttributeView view) Sets an attribute on a FileOwnerAttributeView object.
static void	setAttribute(String attributeName, Object value, PosixFileAttributeView view) Sets an attribute on a PosixFileAttributeView object.
static Map<String,Object>	toAttributeMap(FileAttribute<?>[] attributes, Collection<FileAttributeViewMetadata> supportedViews) Collects several FileAttribute objects into a map.
static Map<String,Object>	toAttributeMap(FileAttribute<?>[] attributes, Collection<FileAttributeViewMetadata> supportedViews, Collection<String> nonSupportedAttributeNames) Collects several FileAttribute objects into a map.
static Map<String,Object>	toAttributeMap(FileAttribute<?>[] attributes, Collection<FileAttributeViewMetadata> supportedViews, String... nonSupportedAttributeNames) Collects several FileAttribute objects into a map.
static Map<String,Object>	toAttributeMap(FileAttribute<?>[] attributes, FileAttributeViewCollection supportedViews) Collects several FileAttribute objects into a map.
static Map<String,Object>	toAttributeMap(FileAttribute<?>[] attributes, FileAttributeViewCollection supportedViews, Collection<String> nonSupportedAttributeNames) Collects several FileAttribute objects into a map.
static Map<String,Object>	toAttributeMap(FileAttribute<?>[] attributes, FileAttributeViewCollection supportedViews, String... nonSupportedAttributeNames) Collects several FileAttribute objects into a map.
static Map<String,Object>	toAttributeMap(FileAttribute<?>[] attributes, FileAttributeViewMetadata... supportedViews) Collects several FileAttribute objects into a map.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getViewName

public static String getViewName(String attributes)

Returns the view name from a string representing attributes to read. This string must be formatted as specified in Files.readAttributes(Path, String, LinkOption...) or Files.setAttribute(Path, String, Object, LinkOption...).

Parameters:

attributes - The string representing the attributes to read.

Returns:

The view name from the string, or basic if the string did not contain a view name.

Throws:

NullPointerException - If the given string is null.

getAttributeName

public static String getAttributeName(String attribute)

Returns the attribute name from a string representing an attribute to be set for a specific view. This string must be formatted as specified in Files.setAttribute(Path, String, Object, LinkOption...).

Parameters:

attribute - The string representing the attribute to set.

Returns:

The attribute name to set.

Throws:

NullPointerException - If the given string is null.

getAttributeNames

public static Set<String> getAttributeNames(String attributes,
                                            FileAttributeViewMetadata view)

Returns the actual attribute names from a string representing attributes to read for a specific view. This string must be formatted as specified in Files.readAttributes(Path, String, LinkOption...).

Parameters:

attributes - The string representing the attributes to read.

view - A FileAttributeViewMetadata object representing the view.

Returns:

A set with the actual attribute names to read.

Throws:

NullPointerException - If the given string or FileAttributeViewMetadata object is null.

IllegalArgumentException - If the string contains a view name that does not match the view name of the given FileAttributeViewMetadata object, or if any of the specified attributes to read is not supported by the view.

populateAttributeMap

public static void populateAttributeMap(Map<String,Object> attributeMap,
                                        BasicFileAttributes fileAttributes,
                                        Set<String> attributeNames)

Populates an attribute map from a BasicFileAttributes object.

Parameters:

attributeMap - The attribute map to populate.

fileAttributes - The BasicFileAttributes with values to populate with.

attributeNames - A set containing the attribute names to populate. This should usually come from getAttributeNames(String, FileAttributeViewMetadata).

Throws:

NullPointerException - If any of the arguments is null.

See Also:

FileSystemProvider.readAttributes(Path, String, LinkOption...)

populateAttributeMap

public static void populateAttributeMap(Map<String,Object> attributeMap,
                                        DosFileAttributes fileAttributes,
                                        Set<String> attributeNames)

Populates an attribute map from a DosFileAttributes object.

Parameters:

attributeMap - The attribute map to populate.

fileAttributes - The BasicFileAttributes with values to populate with.

attributeNames - A set containing the attribute names to populate. This should usually come from getAttributeNames(String, FileAttributeViewMetadata).

Throws:

NullPointerException - If any of the arguments is null.

See Also:

FileSystemProvider.readAttributes(Path, String, LinkOption...)

populateAttributeMap

public static void populateAttributeMap(Map<String,Object> attributeMap,
                                        PosixFileAttributes fileAttributes,
                                        Set<String> attributeNames)

Populates an attribute map from a PosixFileAttributes object.

Parameters:

attributeMap - The attribute map to populate.

fileAttributes - The BasicFileAttributes with values to populate with.

attributeNames - A set containing the attribute names to populate. This should usually come from getAttributeNames(String, FileAttributeViewMetadata).

Throws:

NullPointerException - If any of the arguments is null.

See Also:

FileSystemProvider.readAttributes(Path, String, LinkOption...)

populateAttributeMap

public static void populateAttributeMap(Map<String,Object> attributeMap,
                                        String attributeName,
                                        Set<String> attributeNames,
                                        Supplier<?> getter)

Populates an attribute map with a single attribute. If the given attribute name is not contained in the given set of attribute names, nothing is done.

Parameters:

attributeMap - The attribute map to populate.

attributeName - The name of the attribute to populate.

attributeNames - A set containing the attribute names to populate. This should usually come from getAttributeNames(String, FileAttributeViewMetadata).

getter - A getter for the attribute value.

Throws:

NullPointerException - If any of the arguments is null.

See Also:

FileSystemProvider.readAttributes(Path, String, LinkOption...)

setAttribute

public static void setAttribute(String attributeName,
                                Object value,
                                BasicFileAttributeView view)
                         throws IOException

Sets an attribute on a BasicFileAttributeView object.

Parameters:

attributeName - The name of the attribute to set. It should not be prefixed with the view name; getAttributeName(String) can be used to extract it.

value - The value to set.

view - The view to set the attribute on. IllegalArgumentException If the attribute name is not recognized, or the attribute value is of the correct type but has an inappropriate value. 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.

setAttribute

public static void setAttribute(String attributeName,
                                Object value,
                                FileOwnerAttributeView view)
                         throws IOException

Sets an attribute on a FileOwnerAttributeView object.

Parameters:

attributeName - The name of the attribute to set. It should not be prefixed with the view name; getAttributeName(String) can be used to extract it.

value - The value to set.

view - The view to set the attribute on. IllegalArgumentException If the attribute name is not recognized, or the attribute value is of the correct type but has an inappropriate value. 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.

setAttribute

public static void setAttribute(String attributeName,
                                Object value,
                                DosFileAttributeView view)
                         throws IOException

Sets an attribute on a DosFileAttributeView object.

Parameters:

attributeName - The name of the attribute to set. It should not be prefixed with the view name; getAttributeName(String) can be used to extract it.

value - The value to set.

view - The view to set the attribute on. IllegalArgumentException If the attribute name is not recognized, or the attribute value is of the correct type but has an inappropriate value. 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.

setAttribute

public static void setAttribute(String attributeName,
                                Object value,
                                PosixFileAttributeView view)
                         throws IOException

Sets an attribute on a PosixFileAttributeView object.

Parameters:

attributeName - The name of the attribute to set. It should not be prefixed with the view name; getAttributeName(String) can be used to extract it.

value - The value to set.

view - The view to set the attribute on. IllegalArgumentException If the attribute name is not recognized, or the attribute value is of the correct type but has an inappropriate value. 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.

setAttribute

public static void setAttribute(String attributeName,
                                Object value,
                                AclFileAttributeView view)
                         throws IOException

Sets an attribute on an AclFileAttributeView object.

Parameters:

attributeName - The name of the attribute to set. It should not be prefixed with the view name; getAttributeName(String) can be used to extract it.

value - The value to set.

view - The view to set the attribute on. IllegalArgumentException If the attribute name is not recognized, or the attribute value is of the correct type but has an inappropriate value. 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.

toAttributeMap

public static Map<String,Object> toAttributeMap(FileAttribute<?>[] attributes,
                                                FileAttributeViewMetadata... supportedViews)

Collects several FileAttribute objects into a map. Each entry of the map can be used with FileSystemProvider.setAttribute(Path, String, Object, LinkOption...). Combined with getViewName(String) and getAttributeName(String), each entry can also be used with any of the setAttribute methods of this class.

Parameters:

attributes - The FileAttribute objects to collect.

supportedViews - A number of FileAttributeViewMetadata objects representing the supported views.

Returns:

A map where each key is the name of a given FileAttribute object, prefixed with the matching view name where needed.

Throws:

NullPointerException - If any of the given FileAttribute or FileAttributeViewMetadata objects is null.

UnsupportedOperationException - If any of the given FileAttribute objects refers to a view that is not referred to by any of the given supported FileAttributeViewMetadata objects, or has a non-supported name, or has a value that does not match the expected type.

toAttributeMap

public static Map<String,Object> toAttributeMap(FileAttribute<?>[] attributes,
                                                Collection<FileAttributeViewMetadata> supportedViews)

Collects several FileAttribute objects into a map. Each entry of the map can be used with FileSystemProvider.setAttribute(Path, String, Object, LinkOption...). Combined with getViewName(String) and getAttributeName(String), each entry can also be used with any of the setAttribute methods of this class.

Parameters:

attributes - The FileAttribute objects to collect.

supportedViews - A collection with FileAttributeViewMetadata objects representing the supported views.

Returns:

A map where each key is the name of a given FileAttribute object, prefixed with the matching view name where needed.

Throws:

NullPointerException - If any of the given FileAttribute or FileAttributeViewMetadata objects is null.

UnsupportedOperationException - If any of the given FileAttribute objects refers to a view that is not referred to by any of the given supported FileAttributeViewMetadata objects, or has a non-supported name, or has a value that does not match the expected type.

toAttributeMap

public static Map<String,Object> toAttributeMap(FileAttribute<?>[] attributes,
                                                Collection<FileAttributeViewMetadata> supportedViews,
                                                String... nonSupportedAttributeNames)

Collects several FileAttribute objects into a map. Each entry of the map can be used with FileSystemProvider.setAttribute(Path, String, Object, LinkOption...). Combined with getViewName(String) and getAttributeName(String), each entry can also be used with any of the setAttribute methods of this class.

Parameters:

attributes - The FileAttribute objects to collect.

supportedViews - A collection with FileAttributeViewMetadata objects representing the supported views.

nonSupportedAttributeNames - A collection of attribute names that are not supported, regardless of what the supported views say. This can be used for attributes that cannot be set during creation but only afterwards. Elements should not be prefixed with view names.

Returns:

A map where each key is the name of a given FileAttribute object, prefixed with the matching view name where needed.

Throws:

NullPointerException - If any of the given FileAttribute or FileAttributeViewMetadata objects is null.

UnsupportedOperationException - If any of the given FileAttribute objects refers to a view that is not referred to by any of the given supported FileAttributeViewMetadata objects, or has a non-supported name, or has a value that does not match the expected type.

toAttributeMap

public static Map<String,Object> toAttributeMap(FileAttribute<?>[] attributes,
                                                Collection<FileAttributeViewMetadata> supportedViews,
                                                Collection<String> nonSupportedAttributeNames)

Collects several FileAttribute objects into a map. Each entry of the map can be used with FileSystemProvider.setAttribute(Path, String, Object, LinkOption...). Combined with getViewName(String) and getAttributeName(String), each entry can also be used with any of the setAttribute methods of this class.

Parameters:

attributes - The FileAttribute objects to collect.

supportedViews - A collection with FileAttributeViewMetadata objects representing the supported views.

nonSupportedAttributeNames - A collection of attribute names that are not supported, regardless of what the supported views say. This can be used for attributes that cannot be set during creation but only afterwards. Elements should not be prefixed with view names.

Returns:

A map where each key is the name of a given FileAttribute object, prefixed with the matching view name where needed.

Throws:

NullPointerException - If any of the given FileAttribute or FileAttributeViewMetadata objects is null.

UnsupportedOperationException - If any of the given FileAttribute objects refers to a view that is not referred to by any of the given supported FileAttributeViewMetadata objects, or has a non-supported name, or has a value that does not match the expected type.

toAttributeMap

public static Map<String,Object> toAttributeMap(FileAttribute<?>[] attributes,
                                                FileAttributeViewCollection supportedViews)

Collects several FileAttribute objects into a map. Each entry of the map can be used with FileSystemProvider.setAttribute(Path, String, Object, LinkOption...). Combined with getViewName(String) and getAttributeName(String), each entry can also be used with any of the setAttribute methods of this class.

Parameters:

attributes - The FileAttribute objects to collect.

supportedViews - A collection with FileAttributeViewMetadata objects representing the supported views.

Returns:

A map where each key is the name of a given FileAttribute object, prefixed with the matching view name where needed.

Throws:

NullPointerException - If any of the given FileAttribute objects or the given FileAttributeViewCollection object is null.

UnsupportedOperationException - If any of the given FileAttribute objects refers to a view that is not referred to by any of the given supported FileAttributeViewMetadata objects, or has a non-supported name, or has a value that does not match the expected type.

toAttributeMap

public static Map<String,Object> toAttributeMap(FileAttribute<?>[] attributes,
                                                FileAttributeViewCollection supportedViews,
                                                String... nonSupportedAttributeNames)

Collects several FileAttribute objects into a map. Each entry of the map can be used with FileSystemProvider.setAttribute(Path, String, Object, LinkOption...). Combined with getViewName(String) and getAttributeName(String), each entry can also be used with any of the setAttribute methods of this class.

Parameters:

attributes - The FileAttribute objects to collect.

supportedViews - A collection with FileAttributeViewMetadata objects representing the supported views.

nonSupportedAttributeNames - A collection of attribute names that are not supported, regardless of what the supported views say. This can be used for attributes that cannot be set during creation but only afterwards. Elements should not be prefixed with view names.

Returns:

A map where each key is the name of a given FileAttribute object, prefixed with the matching view name where needed.

Throws:

NullPointerException - If any of the given FileAttribute objects or the given FileAttributeViewCollection object is null.

UnsupportedOperationException - If any of the given FileAttribute objects refers to a view that is not referred to by any of the given supported FileAttributeViewMetadata objects, or has a non-supported name, or has a value that does not match the expected type.

toAttributeMap

public static Map<String,Object> toAttributeMap(FileAttribute<?>[] attributes,
                                                FileAttributeViewCollection supportedViews,
                                                Collection<String> nonSupportedAttributeNames)

Collects several FileAttribute objects into a map. Each entry of the map can be used with FileSystemProvider.setAttribute(Path, String, Object, LinkOption...). Combined with getViewName(String) and getAttributeName(String), each entry can also be used with any of the setAttribute methods of this class.

Parameters:

attributes - The FileAttribute objects to collect.

supportedViews - A collection with FileAttributeViewMetadata objects representing the supported views.

nonSupportedAttributeNames - A collection of attribute names that are not supported, regardless of what the supported views say. This can be used for attributes that cannot be set during creation but only afterwards. Elements should not be prefixed with view names.

Returns:

A map where each key is the name of a given FileAttribute object, prefixed with the matching view name where needed.

Throws:

NullPointerException - If any of the given FileAttribute objects or the given FileAttributeViewCollection object is null.

UnsupportedOperationException - If any of the given FileAttribute objects refers to a view that is not referred to by any of the given supported FileAttributeViewMetadata objects, or has a non-supported name, or has a value that does not match the expected type.