org.asam.ods

Interface ODSFileOperations

All Superinterfaces:

InstanceElementOperations

All Known Subinterfaces:

ODSFile

All Known Implementing Classes:

_ODSFileStub, ODSFile, ODSFile, ODSFilePOA

public interface ODSFileOperations
extends InstanceElementOperations

The interface ODSFile extends the interface InstanceElement. Thus all methods of the interface InstanceElement do also work here. ODSFile allows to create a file that is under control of the ODS server (a 'managed file'). ODSFile furthermore allows read, write, append or remove operations to a managed file. General information of the file can be retrieved from this interface as well. Note, that no random access on a file is provided; only a sequential read and a write by appending at the end is possible. Replacing an existing file by a new one requires first to remove the old one and then create the new one.

Method Summary

Methods

Modifier and Type	Method and Description
ODSWriteTransfer	append() (30000) Get the ODSWriteTransfer interface for the file, to allow appending further bytes to the file.
boolean	canRead() (30001) Check whether the file may be opened for reading.
boolean	canWrite() (30002) Check whether the file may be opened for writing.
ODSWriteTransfer	create() (30003) Create a new file on the host of the ODS server and get the ODSWriteTransfer interface for that file, to allow storing bytes to the file.
boolean	exists() (30004) Check whether the file physically exists at the ODS server.
java.lang.String	getDate() (30005) Get the date of the file.
T_LONGLONG	getSize() (30006) Get the size of the file.
ODSReadTransfer	read() (30008) Get the ODSReadTransfer interface for the file.
void	remove() (30007) Remove a file from the host computer.
void	removeFromControl(java.lang.String targetUrl) (30010) Take a file that is currently under control of the ODS server out of control of the server and move it to a specified location within reach of the server.
void	takeUnderControl(java.lang.String sourceUrl) (30009) Put a file that is already residing within reach of the ODS server under control of the ODS server.

Methods inherited from interface org.asam.ods.InstanceElementOperations

addInstanceAttribute, compare, createRelatedInstances, createRelation, deepCopy, destroy, getApplicationElement, getAsamPath, getId, getInitialRights, getName, getRelatedInstances, getRelatedInstancesByRelationship, getRights, getValue, getValueByBaseName, getValueInUnit, getValueSeq, listAttributes, listRelatedInstances, listRelatedInstancesByRelationship, removeInstanceAttribute, removeRelation, renameInstanceAttribute, setInitialRights, setName, setRights, setValue, setValueSeq, shallowCopy, upcastMeasurement, upcastODSFile, upcastSubMatrix

Method Detail

append

ODSWriteTransfer append()
                        throws AoException

(30000) Get the ODSWriteTransfer interface for the file, to allow appending further bytes to the file. This method returns the ODSWriteTransfer interface for the file represented by this ODSFile object. That interface allows to write sequentially to the file, beginning at the end of the currently existing file. Before returning the interface ODSWriteTransfer, the physical file will be opened for subsequent write operations. In case the current user has no UPDATE right for the instance (resp. for all of its attributes in case of attribute security) from which this ODSFile object was created, the exception AO_ACCESS_DENIED will be thrown. In case the physical file referenced by this ODSFile object cannot be found, the exception AO_BAD_OPERATION will be thrown. In case the physical file referenced by this ODSFile object is currently opened by an ODSReadTransfer or an ODSWriteTransfer object, the exception AO_FILE_LOCKED will be thrown. In case the file cannot be opened for writing the exception AO_SYSTEM_PROBLEM will be thrown.

Returns:

The ODSWriteTransfer interface to append to the file.

Throws:

AoException - with the following possible error codes: AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE AO_FILE_LOCKED AO_ACCESS_DENIED AO_BAD_OPERATION AO_SYSTEM_PROBLEM

canRead

boolean canRead()
                throws AoException

(30001) Check whether the file may be opened for reading. This method checks whether the file represented by this ODSFile object may be opened by the ODS server for reading access. The method returns a boolean TRUE in case the file may be opened for reading, and a boolean FALSE in case it cannot be opened for reading or it is already opened for write access (i.e. an ODSWriteTransfer object for this file exists). In case the physical file referenced by this ODSFile object cannot be found, false will be returned.

Returns:

Information about whether the file can be opened for reading

Throws:

AoException - with the following possible error codes: AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

canWrite

boolean canWrite()
                 throws AoException

(30002) Check whether the file may be opened for writing. This method checks whether the file represented by this ODSFile object may be opened by the ODS server for writing access. The method returns a boolean TRUE in case the user has appropriate rights and the file can be opened for writing, and a boolean FALSE in case it is already opened for write access (i.e. an ODSWriteTransfer object for this file exists) or for read access (i.e. one or more ODSReadTransfer objects for this file exist). In case ao_location is defined and the current user has no UPDATE right for the instance from which this ODSFile object was created, a boolean FALSE will be returned. In case ao_location is undefined and the current user has no INSERT right for the instance from which this ODSFile object was created, a boolean FALSE will be returned.

Returns:

Information about whether the file can be opened for writing

Throws:

AoException - with the following possible error codes: AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

create

ODSWriteTransfer create()
                        throws AoException

(30003) Create a new file on the host of the ODS server and get the ODSWriteTransfer interface for that file, to allow storing bytes to the file. This method returns the ODSWriteTransfer interface for the file represented by this ODSFile object. That interface allows to write sequentially to the (initially empty) file. Before returning the interface ODSWriteTransfer, the physical file will be created on the host computer with the ODS server and opened for subsequent write operations. The file name will be decided by the ODS server and set as value of the attribute derived from the base attribute 'ao_location' of the instance from which this ODSFile object was created. In case the current user has no INSERT right for the instance from which this ODSFile object was created, the exception AO_ACCESS_DENIED will be thrown. If the attribute derived from 'ao_location' of the instance from which this ODSFile object was created already has a value, the instance potentially already references a file which was not yet removed, and the server will check whether that former file still exists. If so the exception AO_BAD_OPERATION will be thrown and no new file will be created. In case the file cannot be opened for writing the exception AO_SYSTEM_PROBLEM will be thrown.

Returns:

The ODSWriteTransfer interface to a new file.

Throws:

AoException - with the following possible error codes: AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE AO_ACCESS_DENIED AO_BAD_OPERATION AO_SYSTEM_PROBLEM

exists

boolean exists()
               throws AoException

(30004) Check whether the file physically exists at the ODS server. This method checks whether the file represented by this ODSFile object truly exists at the expected location (e.g. on a specific drive/directory) within reach of the ODS server. The method returns a boolean TRUE in case the file exists, and a boolean FALSE in case it does not exist.

Returns:

Information about whether the file exists.

Throws:

AoException - with the following possible error codes: AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

getDate

java.lang.String getDate()
                         throws AoException

(30005) Get the date of the file. This method returns the date of the file represented by this ODSFile object. The returned string follows the rules for ODS date and time specification strings. The date returned shall specify the timestamp of the latest change of the file. It is the information the operating system of the host computer provides where the ODS server is installed; if there is no date available from the operating system with exactly this meaning, the ODS server shall return the closest information available. In case the physical file referenced by this ODSFile object cannot be found, the exception AO_SYSTEM_PROBLEM will be thrown. In case the physical file referenced by this ODSFile object is currently opened by an ODSWriteTransfer object of another session, the exception AO_FILE_LOCKED will be thrown. In case there is no file defined by the attribute derived from 'ao_location', the exception AO_BAD_OPERATION will be thrown.

Returns:

The date of last change of the file represented by this ODSFile object.

Throws:

AoException - with the following possible error codes: AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE AO_BAD_OPERATION AO_SYSTEM_PROBLEM AO_FILE_LOCKED

getSize

T_LONGLONG getSize()
                   throws AoException

(30006) Get the size of the file. This method returns the size of the file represented by this ODSFile object. The returned value shall specify the exact file size in bytes. It is the information the operating system of the host computer provides where the ODS server is installed. In case the physical file referenced by this ODSFile object cannot be found, the exception AO_SYSTEM_PROBLEM will be thrown. In case there is no file defined by the attribute derived from 'ao_location', the exception AO_BAD_OPERATION will be thrown. In case the physical file referenced by this ODSFile object is currently opened by an ODSWriteTransfer object of another session, the exception AO_FILE_LOCKED will be thrown.

Returns:

The size in bytes of the file represented by this ODSFile object.

Throws:

AoException - with the following possible error codes: AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE AO_FILE_LOCKED AO_BAD_OPERATION AO_SYSTEM_PROBLEM

remove

void remove()
            throws AoException

(30007) Remove a file from the host computer. This method physically deletes the file represented by this ODSFile object from the host computer if the user has appropriate rights. The attribute derived from the base attribute 'ao_location' of the instance from which this ODSFile object was created will become undefined and ao_size will be set to 0. In case the current user has no DELETE right for the instance from which this ODSFile object was created, the exception AO_ACCESS_DENIED will be thrown. In case the file is currently opened for write access (i.e. an ODSWriteTransfer object for this file exists) or for read access (i.e. one or more ODSReadTransfer objects for this file exist) an exception AO_FILE_LOCKED will be thrown. In case the physical file referenced by this ODSFile object does not exist, the method will return without any further file action; it will set the attribute derived from the base attribute 'ao_location' to undefined and 'ao_size' to 0; it will not throw an exception to signal the non-existence of the file. In case the file cannot be physically deleted from its location, the exception AO_SYSTEM_PROBLEM will be thrown.

Throws:

AoException - with the following possible error codes: AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE AO_FILE_LOCKED AO_ACCESS_DENIED AO_SYSTEM_PROBLEM

read

ODSReadTransfer read()
                     throws AoException

(30008) Get the ODSReadTransfer interface for the file. This method returns the ODSReadTransfer interface for the file represented by this ODSFile object. That interface allows to read sequentially from the file, either starting at the very beginning or at a user-specified byte location within the file. Before returning the interface ODSReadTransfer, the physical file will be opened for reading. In case the physical file referenced by this ODSFile object is currently opened by an ODSWriteTransfer object, the exception AO_FILE_LOCKED will be thrown. In case there is no file defined by the attribute derived from 'ao_location', the exception AO_BAD_OPERATION will be thrown. In case the attribute derived from 'ao_location' is defined but the physical file referenced by this ODSFile object cannot be found or cannot be opened for reading, the exception AO_SYSTEM_PROBLEM will be thrown.

Returns:

The ODSReadTransfer interface to read from the file.

Throws:

AoException - with the following possible error codes: AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE AO_FILE_LOCKED AO_BAD_OPERATION AO_SYSTEM_PROBLEM

takeUnderControl

void takeUnderControl(java.lang.String sourceUrl)
                      throws AoException

(30009) Put a file that is already residing within reach of the ODS server under control of the ODS server. This method allows to put files under control of the ODS server (make them a 'managed file') without the need to stream their bytes through the ODSWriteTransfer interface. The parameter 'sourceUrl' specifies the location of the file that shall become a managed file. This location must reference a file which is accessible by the server. The server will move the file to a location where managed files reside and give it a name of its own choice; the file will no longer exist at its previous location. The server will store file name and location in the attribute derived from 'ao_location' and store the size of the file in the attribute derived from 'ao_size'. The string value of 'sourceUrl' must comply to the URL specification given in RFC 2396 with the restriction that ASAM ODS only supports absolute URLs with the access scheme "file:", otherwise the exception AO_BAD_PARAMETER will be thrown. In case there is no file defined by the attribute derived from 'ao_location', the exception AO_BAD_OPERATION will be thrown. In case the file cannot be physically moved from its original location to a server-location where managed files reside, the exception AO_SYSTEM_PROBLEM will be thrown (e.g. if the file specified by 'sourceUrl' does not exist, or if it cannot be physically moved, etc.).

Parameters:

sourceUrl - Filename URL of the file to take under control as a managed file.

Throws:

AoException - with the following possible error codes: AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE AO_BAD_PARAMETER AO_BAD_OPERATION AO_SYSTEM_PROBLEM

removeFromControl

void removeFromControl(java.lang.String targetUrl)
                       throws AoException

(30010) Take a file that is currently under control of the ODS server out of control of the server and move it to a specified location within reach of the server. This method allows to take files out of control of the ODS server and place them at a specified location, without the need to stream their bytes through the ODSReadTransfer interface. The parameter 'targetUrl' specifies the location to which the currently managed file shall be moved. This location must be accessible by the server. The server will move the file from the location where managed files reside to the location given by 'targetUrl'; the file will no longer exist at its previous location. The server will set the value of the attribute derived from 'ao_location' to undefined and of the attribute derived from 'ao_size' to 0. The string value of 'targetUrl' must comply to the URL specification given in RFC 2396 with the restriction that ASAM ODS only supports absolute URLs with the access scheme "file:"; otherwise the exception AO_BAD_PARAMETER will be thrown. In case the file specified by 'targetUrl' already exists the exception AO_BAD_PARAMETER will be thrown and no action will be performed by this method. In case the file specified by 'targetUrl' cannot be physically moved to the intended location, the exception AO_SYSTEM_PROBLEM will be thrown and no action will be performed by this method. In case the file referenced by this ODSFile object is currently opened for write access (i.e. an ODSWriteTransfer object for this file exists) or for read access (i.e. one or more ODSReadTransfer objects for this file exist) an exception AO_FILE_LOCKED will be thrown and no action will be performed by this method. In case there is no file defined by the attribute derived from 'ao_location', the exception AO_BAD_OPERATION will be thrown.

Parameters:

targetUrl - Filename URL of the file where to move the managed file.

Throws:

AoException - with the following possible error codes: AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE AO_BAD_PARAMETER AO_FILE_LOCKED AO_SYSTEM_PROBLEM AO_BAD_OPERATION AO_BAD_PARAMETER