public interface IFileHelper
IFileHelper provides access methods used for handling
files for document generation. The IFileHelper can be
referenced directly within a document template by its name
fileHelper.
| Modifier and Type | Method and Description |
|---|---|
java.lang.String |
addExtensionIfMissing(java.lang.String fileName,
java.lang.String extension)
Adds a certain file extension, if none is existing.
|
java.lang.String |
convertStringToPortableFileName(java.lang.String string)
Replaces all invalid characters in a file name by underscores
|
boolean |
copyDirectoryContent(java.lang.String srcDirectoryName,
java.lang.String trgtDirectoryName)
copies a directory's content into another directory
|
boolean |
copyFile(java.lang.String sourceName,
java.lang.String destinationName)
copies a file from
source to destination |
java.lang.String |
createPostProcessingFile(java.lang.String fileName)
Creates a file name.
|
IRecord |
decodeRecordFromXMLFile(java.lang.String fileNameOfFileToBeRead)
Decodes a record from an XML file.
|
IRecord |
decodeRecordFromXMLString(java.lang.String xmlString,
java.lang.String encoding)
Decodes a record from an XML String.
|
boolean |
deleteContentOfDirectory(java.lang.String directoryName)
deletes the content of the directory but not the directory itself
|
boolean |
deleteExistingFileOrDirectory(java.lang.String fileOrDirectoryName)
Deletes
- a File or - a Directory and its contents (recursively) |
boolean |
deleteFileOrDirectory(java.lang.String fileOrDirectoryName)
Deletes
- a File or - a Directory and its contents (recursively) if it exists. |
boolean |
doesDirectoryContainEssentialFiles(java.lang.String directoryName,
boolean ignoreDirectoryEntries,
boolean ignoreAuxiliaryFiles)
Checks if a directory contains relevant files.
|
java.lang.String |
encodeRecordIntoPreprocessingXMLFile(IRecord record,
java.lang.String rootName,
java.lang.String namespace,
java.lang.String encoding,
boolean formatOutput)
Encodes a record into a temporary XML file.
|
java.lang.String |
encodeRecordIntoXMLString(IRecord record,
java.lang.String rootName,
java.lang.String namespace,
java.lang.String encoding,
boolean formatOutput)
Encodes a record into an XML String.
|
boolean |
ensureDirectoryExistance(java.lang.String directoryName)
ensureDirectoryExisitance
|
java.lang.String |
getChild(java.lang.String parentFileName,
java.lang.String childName)
Creates a filename from a parent pathname string
and a child pathname string.
|
java.lang.String |
getFileExtension(java.lang.String fileName)
Extracts the file extension from the given file name.
|
java.lang.String |
getFileNameWithoutPath(java.lang.String fileName)
Returns the name of the file or directory denoted by an abstract
pathname.
|
java.lang.String |
getParent(java.lang.String fileName)
Returns the pathname string of the parent, or
null if the pathname does not name a parent directory. |
boolean |
isDirectory(java.lang.String fileName)
Tests whether the file denoted by this abstract pathname is a
directory.
|
boolean |
isFile(java.lang.String fileName)
Tests whether the file denoted by this abstract pathname is a normal
file.
|
boolean |
isHidden(java.lang.String fileName)
Tests whether the file named by this abstract pathname is a hidden
file.
|
long |
lastModified(java.lang.String fileName)
Returns the time that the file denoted by this abstract pathname was
last modified.
|
long |
length(java.lang.String fileName)
Returns the length of the file denoted by this abstract pathname.
|
java.util.Collection<java.lang.String> |
listDirectoryContent(java.lang.String directory)
Returns the names of all files and folders of a certain directory.
|
IRecord |
loadXMLFileIntoRecord(java.lang.String fileNameOfFileToBeRead)
Loads an XML file into a record.
|
IRecord |
loadXMLFileIntoRecord(java.lang.String xmlString,
java.lang.String encoding)
Loads an XML file (represented as string) into a record.
|
boolean |
moveFile(java.lang.String sourceFileName,
java.lang.String destinationFileName)
moves a file from
source to destination The
destination file is deleted if it already exists. |
java.util.List<java.lang.String> |
readFileIntoBase64StringList(java.lang.String fileName,
boolean breakLines)
Returns the content of a file as string list (Base64 encoded).
|
java.util.List<java.lang.String> |
readFileIntoStringList(java.lang.String fileName,
java.lang.String characterEncoding)
Returns the content of a file as string list.
|
IImageInfo |
readImageInfo(java.lang.String imagefileName)
Returns meta information regarding a certain image file.
|
java.lang.String |
saveXMLFileFromRecordIntoPreprocessingXMLFile(IRecord record,
java.lang.String fileNamePrefix,
java.lang.String encoding,
int formatOutput)
Stores an XML file as contained in a record into a temporary XML file.
|
java.lang.String |
saveXMLFileFromRecordIntoXMLString(IRecord record,
java.lang.String encoding,
int formatOutput)
Stores an XML file as contained in a record into a XML String.
|
boolean |
setLastModified(java.lang.String fileName,
long time)
Sets the last-modified time of the file or directory named by this
abstract pathname.
|
boolean |
setReadOnly(java.lang.String fileName)
Marks the file or directory named by this abstract pathname so that
only read operations are allowed.
|
java.lang.String |
shortenFileName(java.lang.String fileName,
int maxLength)
Shortens the name to the specidfied maximum length while preserving
the file extension.
|
java.lang.String |
writeBase64IntoPostProcessingFile(java.util.List<java.lang.String> base64FileContent,
java.lang.String originalFileName)
Writes a base64 encoded content into the report as an embedded file.
|
java.lang.String |
writeBase64IntoPostProcessingFile(java.util.List<java.lang.String> base64FileContent,
java.lang.String originalFileName,
double width_mm,
double height_mm)
Writes a base64 encoded content into the report as an embedded file.
|
java.lang.String |
writeBase64IntoPreProcessingFile(java.util.List<java.lang.String> base64FileContent,
java.lang.String prefix,
java.lang.String extension)
Writes a base64 encoded content into a temporary file.
|
java.lang.String |
writeDecoratedImage(java.lang.String fileNameOfImageToDecorate,
double toGray,
java.lang.String fileNameOfDecoratorImage)
Writes an image into the report as an embedded file.
|
java.lang.String |
writeDecoratedImage(java.lang.String fileNameOfImageToDecorate,
double toGray,
java.lang.String fileNameOfDecoratorImage,
double width_mm,
double height_mm)
Writes an image into the report as an embedded file.
|
java.lang.String |
writeDecoratedImageAligned(java.lang.String fileNameOfImageToDecorate,
double toGray,
int baseAlignX,
int baseAlignY,
java.lang.String fileNameOfDecoratorImage,
int alignX,
int alignY,
int offX,
int offY)
Writes an image into the report as an embedded file.
|
java.lang.String |
writeDecoratedImageAligned(java.lang.String fileNameOfImageToDecorate,
double toGray,
int baseAlignX,
int baseAlignY,
java.lang.String fileNameOfDecoratorImage,
int alignX,
int alignY,
int offX,
int offY,
double width_mm,
double height_mm)
Writes an image into the report as an embedded file.
|
java.lang.String |
writeDecoratedImageAlignedIntoPreProcessingFile(java.lang.String fileNameOfImageToDecorate,
double toGray,
int baseAlignX,
int baseAlignY,
java.lang.String fileNameOfDecoratorImage,
int alignX,
int alignY,
int offX,
int offY)
Writes an image into into a temporary file.
|
java.lang.String |
writeStringListIntoPreProcessingFile(java.util.List<java.lang.String> stringList,
java.lang.String prefix,
java.lang.String extension,
java.lang.String characterEncoding,
boolean addCR,
boolean addLF)
Writes a string array into a temporary file.
|
java.util.List<java.lang.String> readFileIntoStringList(java.lang.String fileName,
java.lang.String characterEncoding)
fileName - file namecharacterEncoding - the encoding to be used when reading the
filejava.lang.String writeStringListIntoPreProcessingFile(java.util.List<java.lang.String> stringList,
java.lang.String prefix,
java.lang.String extension,
java.lang.String characterEncoding,
boolean addCR,
boolean addLF)
throws java.io.IOException
The file is created a temporary directory. The file can be accessed during document generation. It will not be available anymore from the target output.
stringList - file contentprefix - file name prefixextension - file extensioncharacterEncoding - character encodingaddCR - add CR after each lineaddLF - add LF after each linejava.io.IOExceptionjava.lang.String writeBase64IntoPreProcessingFile(java.util.List<java.lang.String> base64FileContent,
java.lang.String prefix,
java.lang.String extension)
throws java.io.IOException
The file is created a temporary directory. The file can be accessed during document generation. It will not be available anymore from the target output.
stringList - file contentprefix - file name prefixextension - file extensionjava.io.IOExceptionjava.util.List<java.lang.String> readFileIntoBase64StringList(java.lang.String fileName,
boolean breakLines)
fileName - file namefileName - the local file nameIImageInfo readImageInfo(java.lang.String imagefileName)
imagefileName - the image file namejava.lang.String writeBase64IntoPostProcessingFile(java.util.List<java.lang.String> base64FileContent,
java.lang.String originalFileName)
throws java.io.IOException
The file could be embedded in the target output.
stringList - file contentoriginalFileName - original file namejava.io.IOExceptionjava.lang.String writeBase64IntoPostProcessingFile(java.util.List<java.lang.String> base64FileContent,
java.lang.String originalFileName,
double width_mm,
double height_mm)
throws java.io.IOException
The file could be embedded in the target output. If the file represents an image, width and height can be specified (0 = unspecified)
stringList - file contentoriginalFileName - original file namewidth_mm - width in mm (0 = unspecified)height_mm - height in mm (0 = unspecified)java.io.IOExceptionjava.lang.String writeDecoratedImage(java.lang.String fileNameOfImageToDecorate,
double toGray,
java.lang.String fileNameOfDecoratorImage,
double width_mm,
double height_mm)
The image is created by decorating one image with another. The decorater is placed in the lower right of the image. The resulting image could be embedded in the target output.
Call writeBase64IntoPreProcessingFile(List, String, String),
ICustomPropertiesAccess#getFilePropertyAsFileName(String, String)
or
{@link #writeDecoratedImageAlignedIntoPreProcessingFile(String, double, int, int, String, int, int, int, int)}
to get the file names.
fileNameOfImageToDecorate - toGray - 0 (leave image to decorate as is) .. 1 (gray)fileNameOfDecoratorImage - width_mm - width in mm (0 = unspecified)height_mm - height in mm (0 = unspecified)java.io.IOExceptionjava.lang.String writeDecoratedImage(java.lang.String fileNameOfImageToDecorate,
double toGray,
java.lang.String fileNameOfDecoratorImage)
The image is created by decorating one image with another. The decorater is placed in the lower right of the image. The resulting image could be embedded in the target output.
Call writeBase64IntoPreProcessingFile(List, String, String),
ICustomPropertiesAccess#getFilePropertyAsFileName(String, String)
or
{@link #writeDecoratedImageAlignedIntoPreProcessingFile(String, double, int, int, String, int, int, int, int)}
to get the file names.
fileNameOfImageToDecorate - toGray - 0 (leave image to decorate as is) .. 1 (gray)fileNameOfDecoratorImage - java.io.IOExceptionjava.lang.String writeDecoratedImageAligned(java.lang.String fileNameOfImageToDecorate,
double toGray,
int baseAlignX,
int baseAlignY,
java.lang.String fileNameOfDecoratorImage,
int alignX,
int alignY,
int offX,
int offY)
The image is created by decorating one image with another. The decorater is placed in the lower right of the image. The resulting image could be embedded in the target output.
Call writeBase64IntoPreProcessingFile(List, String, String),
ICustomPropertiesAccess#getFilePropertyAsFileName(String, String)
or
{@link #writeDecoratedImageAlignedIntoPreProcessingFile(String, double, int, int, String, int, int, int, int)}
to get the file names.
fileNameOfImageToDecorate - toGray - 0 (leave image to decorate as is) .. 1 (gray)baseAlignX - alignment within image to decorate: 0 = left
border, 1 = center, 2 = right borderbaseAlignX - alignment within image to decorate: 0 = top, 1 =
center, 2 = bottomfileNameOfDecoratorImage - alignX - alignment of decorator image: 0 = flow to the left, 1 =
centered, 2 = flow to the rightalignY - alignment of decorator image: 0 = flow upwards, 1 =
centered, 2 = flow downwardsoffX - offset X in pixels (positive = move to right)offY - offset Y in pixels (positive = move downwards)java.io.IOExceptionjava.lang.String writeDecoratedImageAligned(java.lang.String fileNameOfImageToDecorate,
double toGray,
int baseAlignX,
int baseAlignY,
java.lang.String fileNameOfDecoratorImage,
int alignX,
int alignY,
int offX,
int offY,
double width_mm,
double height_mm)
The image is created by decorating one image with another. The decorater is placed in the lower right of the image. The resulting image could be embedded in the target output.
Call writeBase64IntoPreProcessingFile(List, String, String),
ICustomPropertiesAccess#getFilePropertyAsFileName(String, String)
or
{@link #writeDecoratedImageAlignedIntoPreProcessingFile(String, double, int, int, String, int, int, int, int)}
to get the file names.
fileNameOfImageToDecorate - toGray - 0 (leave image to decorate as is) .. 1 (gray)baseAlignX - alignment within image to decorate: 0 = left
border, 1 = center, 2 = right borderbaseAlignX - alignment within image to decorate: 0 = top, 1 =
center, 2 = bottomfileNameOfDecoratorImage - alignX - alignment of decorator image: 0 = flow to the left, 1 =
centered, 2 = flow to the rightalignY - alignment of decorator image: 0 = flow upwards, 1 =
centered, 2 = flow downwardsoffX - offset X in pixels (positive = move to right)offY - offset Y in pixels (positive = move downwards)width_mm - width in mm (0 = unspecified)height_mm - height in mm (0 = unspecified)java.io.IOExceptionjava.lang.String writeDecoratedImageAlignedIntoPreProcessingFile(java.lang.String fileNameOfImageToDecorate,
double toGray,
int baseAlignX,
int baseAlignY,
java.lang.String fileNameOfDecoratorImage,
int alignX,
int alignY,
int offX,
int offY)
The file is created a temporary directory. The file can be accessed during document generation. It will not be available anymore from the target output.
The image is created by decorating one image with another. The decorater is placed in the lower right of the image.
Call writeBase64IntoPreProcessingFile(List, String, String),
ICustomPropertiesAccess#getFilePropertyAsFileName(String, String)
or
{@link #writeDecoratedImageAlignedIntoPreProcessingFile(String, double, int, int, String, int, int, int, int)}
to get the file names.
fileNameOfImageToDecorate - toGray - 0 (leave image to decorate as is) .. 1 (gray)baseAlignX - alignment within image to decorate: 0 = left
border, 1 = center, 2 = right borderbaseAlignX - alignment within image to decorate: 0 = top, 1 =
center, 2 = bottomfileNameOfDecoratorImage - alignX - alignment of decorator image: 0 = flow to the left, 1 =
centered, 2 = flow to the rightalignY - alignment of decorator image: 0 = flow upwards, 1 =
centered, 2 = flow downwardsoffX - offset X in pixels (positive = move to right)offY - offset Y in pixels (positive = move downwards)java.io.IOExceptionjava.lang.String encodeRecordIntoPreprocessingXMLFile(IRecord record, java.lang.String rootName, java.lang.String namespace, java.lang.String encoding, boolean formatOutput) throws com.arcway.lib.codec.xml.EXXMLEncodingFailed
The file is created a temporary directory. The file can be accessed during document generation. It will not be available anymore from the target output.
record - rootName - the name for the XML root element (must not be null)namespace - the namespace (null for none)encoding - the encoding (e.g. "UTF-8") (must be valid supported
and not null)formatOutput - true if the output should be formatted (with
indents and line feeds), false if notcom.arcway.lib.codec.xml.EXXMLEncodingFailed - if encoding failed for some reasonjava.lang.String encodeRecordIntoXMLString(IRecord record, java.lang.String rootName, java.lang.String namespace, java.lang.String encoding, boolean formatOutput) throws com.arcway.lib.codec.xml.EXXMLEncodingFailed
record - rootName - the name for the XML root element (must not be null)namespace - the namespace (null for none)encoding - the encoding (e.g. "UTF-8") (must be valid supported
and not null)formatOutput - true if the output should be formatted (with
indents and line feeds), false if notcom.arcway.lib.codec.xml.EXXMLEncodingFailed - if encoding failed for some reasonIRecord decodeRecordFromXMLFile(java.lang.String fileNameOfFileToBeRead) throws com.arcway.lib.codec.xml.EXXMLDecodingFailed, java.io.IOException
fileNameOfFileToBeRead - the xml file (must not be null)java.io.UnsupportedEncodingExceptioncom.arcway.lib.codec.xml.EXXMLDecodingFailed - if decoding failed for some reasonjava.io.FileNotFoundExceptionjava.io.IOExceptionIRecord decodeRecordFromXMLString(java.lang.String xmlString, java.lang.String encoding) throws java.io.UnsupportedEncodingException, com.arcway.lib.codec.xml.EXXMLDecodingFailed
xmlString - the xmlString (must not be null)encoding - the encoding (must be the same that is stated in the
XML header!)java.io.UnsupportedEncodingExceptioncom.arcway.lib.codec.xml.EXXMLDecodingFailed - if decoding failed for some reasonIRecord loadXMLFileIntoRecord(java.lang.String fileNameOfFileToBeRead) throws com.arcway.lib.codec.xml.EXXMLDecodingFailed, java.io.IOException
IRecords containing the child XML elements (syntax is same like for this element), orXMLProcessingInstructionsfileNameOfFileToBeRead - the xml file (must not be null)java.io.UnsupportedEncodingExceptioncom.arcway.lib.codec.xml.EXXMLDecodingFailed - if decoding failed for some reasonjava.io.FileNotFoundExceptionjava.io.IOExceptionIRecord loadXMLFileIntoRecord(java.lang.String xmlString, java.lang.String encoding) throws java.io.UnsupportedEncodingException, com.arcway.lib.codec.xml.EXXMLDecodingFailed
loadXMLFileIntoRecord(String)fileNameOfFileToBeRead - the xml file (must not be null)java.io.UnsupportedEncodingExceptioncom.arcway.lib.codec.xml.EXXMLDecodingFailed - if decoding failed for some reasonjava.io.FileNotFoundExceptionjava.io.IOExceptionjava.lang.String saveXMLFileFromRecordIntoPreprocessingXMLFile(IRecord record, java.lang.String fileNamePrefix, java.lang.String encoding, int formatOutput) throws com.arcway.lib.codec.xml.EXXMLEncodingFailed
The file is created a temporary directory. The file can be accessed
during document generation. It will not be available anymore from the
target output.
Note: This method can store any XML file. Therefore the record needs to follow a given syntax as described here: loadXMLFileIntoRecord(String).
For creating XML processing instructions, see also: IArrayHelper.createProcessingInstruction(String, String)
record - fileNamePrefix - a prefix for the filename of the temp file (file extension is ".xml")encoding - the encoding (e.g. "UTF-8") (must be valid supported
and not null)formatOutput - 0 if the output should not be formatted, -1 or 1 if the output should be formatted (with
indents and line feeds), 2 is like 0, but CR, LF and TABs are not escapedcom.arcway.lib.codec.xml.EXXMLEncodingFailed - if encoding failed for some reasonjava.lang.String saveXMLFileFromRecordIntoXMLString(IRecord record, java.lang.String encoding, int formatOutput) throws com.arcway.lib.codec.xml.EXXMLEncodingFailed
loadXMLFileIntoRecord(String).
For creating XML processing instructions, see also: IArrayHelper.createProcessingInstruction(String, String)record - encoding - the encoding (e.g. "UTF-8") (must be valid supported
and not null)formatOutput - 0 if the output should not be formatted, -1 or 1 if the output should be formatted (with
indents and line feeds), 2 is like 0, but CR, LF and TABs are not escapedcom.arcway.lib.codec.xml.EXXMLEncodingFailed - if encoding failed for some reasonjava.lang.String createPostProcessingFile(java.lang.String fileName)
The file could be embedded in the target output.
graphicsAndFilesHelper - fileName - file name with extension (no path name, special
characters should be avoided, length > 32 should be avoided)java.lang.String addExtensionIfMissing(java.lang.String fileName,
java.lang.String extension)
fileName - the file or path nameextension - the extension to add (e.g. "png"), without the
separatorboolean moveFile(java.lang.String sourceFileName,
java.lang.String destinationFileName)
source to destination The
destination file is deleted if it already exists.sourceFileName - destinationFileName - boolean deleteFileOrDirectory(java.lang.String fileOrDirectoryName)
fileOrDirectoryName - (must not be null)boolean deleteExistingFileOrDirectory(java.lang.String fileOrDirectoryName)
fileOrDirectoryName - (must not be null)boolean deleteContentOfDirectory(java.lang.String directoryName)
directoryName - boolean ensureDirectoryExistance(java.lang.String directoryName)
directory - (if null, this method does nothing)boolean copyFile(java.lang.String sourceName,
java.lang.String destinationName)
source to destinationsourceName - destinationName - boolean copyDirectoryContent(java.lang.String srcDirectoryName,
java.lang.String trgtDirectoryName)
srcDirectoryName - trgtDirectoryName - java.lang.String getFileExtension(java.lang.String fileName)
fileName - the fileNameboolean doesDirectoryContainEssentialFiles(java.lang.String directoryName,
boolean ignoreDirectoryEntries,
boolean ignoreAuxiliaryFiles)
directoryName - ignoreDirectoryEntries - directories are ignored if they itself
contain no essential filesignoreAuxiliaryFiles - ignored files are ".DS_Store",
"Thumbs.db and all files starting with "._".java.lang.String convertStringToPortableFileName(java.lang.String string)
string - the name of the file with or without extension but
without any pathsjava.lang.String shortenFileName(java.lang.String fileName,
int maxLength)
ATTENTION: If the maximum length is shorter or equal to the
length of the extension plus the extension separator, then at least
one character of the filename is preserverd. That means that the
resulting string always has at least a lenght of
lengthOfExtension + 2.
Examples:
VeryLongFileName.png with a specified maximum length of
10 results in VeryLo.png
VeryLongFileName.png with a specified maximum length of
3 results in V.png VeryLongFileName with a
specified maximum length of 10 results in VeryLongFi
VeryLongFileName with a specified maximum length of 3
results in Ver
fileName - the name of the file with or without extension but
without any pathsmaxLength - the maximum length of the file name (includes
extension)java.util.Collection<java.lang.String> listDirectoryContent(java.lang.String directory)
java.lang.String getFileNameWithoutPath(java.lang.String fileName)
java.lang.String getParent(java.lang.String fileName)
null if the pathname does not name a parent directory.
The parent of an abstract pathname consists of the pathname's prefix, if any, and each name in the pathname's name sequence except for the last. If the name sequence is empty then the pathname does not name a parent directory.
null if this pathname
does not name a parentjava.lang.String getChild(java.lang.String parentFileName,
java.lang.String childName)
If parent is null then the
resulting pathname is created as if only child is given.
Otherwise the parent pathname string is taken to denote
a directory, and the child pathname string is taken to
denote either a directory or a file. If parent is the empty string then
the file name is created by resolving the child
against a system-dependent default directory. Otherwise the child
pathname is resolved against the parent.
parent - The parent pathname stringchild - The child pathname stringjava.lang.NullPointerException - If child is nullboolean isDirectory(java.lang.String fileName)
true if and only if the file denoted by this
abstract pathname exists and is a directory;
false otherwiseboolean isFile(java.lang.String fileName)
true if and only if the file denoted by this
abstract pathname exists and is a normal file;
false otherwiseboolean isHidden(java.lang.String fileName)
'.'). On Microsoft Windows systems, a file is
considered to be hidden if it has been marked as such in the filesystem.true if and only if the file denoted by this
abstract pathname is hidden according to the conventions of the
underlying platformlong lastModified(java.lang.String fileName)
long value representing the time the file was
last modified, measured in milliseconds since the epoch
(00:00:00 GMT, January 1, 1970), or 0L if the
file does not exist or if an I/O error occurslong length(java.lang.String fileName)
0L if the file does not exist. Some
operating systems may return 0L for pathnames
denoting system-dependent entities such as devices or pipes.boolean setLastModified(java.lang.String fileName,
long time)
All platforms support file-modification times to the nearest second,
but some provide more precision. The argument will be truncated to fit
the supported precision. If the operation succeeds and no intervening
operations on the file take place, then the next invocation of the
method will return the (possibly
truncated) lastModified(java.lang.String)time argument that was passed to this method.
time - The new last-modified time, measured in milliseconds since
the epoch (00:00:00 GMT, January 1, 1970)true if and only if the operation succeeded;
false otherwisejava.lang.IllegalArgumentException - If the argument is negativeboolean setReadOnly(java.lang.String fileName)
true if and only if the operation succeeded;
false otherwise