Copyright 1992, 1993  by Allegheny College

FileRetriever

INHERITS FROM	Object

DECLARED IN	FileRetriever.h

WRITTEN BY	Charles G. Fleming and Judy D. Halchin

CLASS DESCRIPTION

A FileRetriever is an object that performs most of the steps needed to allow a user to open a file and read data from it.  It has an open: method which performs the action for the standard Open menu choice.  Methods are also provided for saving files programmatically (see open, setFilname: and setDirectory:).

A FileRetriever must have a dataDelegate which implements the readDataFromStream: method.  It is the responsibility of the dataDelegate to read the data from the stream provided as an argument to this method.  A FileRetriever may also have a delegate, which will receive the dataWasRead:success:errorCode message informing the delegate whether or not the data was successfully read from the file.  An associated FileSaver instance is also optional.

INSTANCE VARIABLES

Inherited from Object	Class	isa;

Declared in FileRetriever	id	delegate;
	id	dataDelegate;
	id	fileSaver;
	char 	*filename;
	char 	*directory;

delegate 	The object that will receive notification of whether a file was opened. 

dataDelegate 	The object responsible for reading the data from the stream.

fileSaver 	The FileSaver that works with this instance of FileRetriever. 

filename 	The name of the data file.

directory 	The full path to the directory of the data file.

METHOD TYPES

Initializing a new FileRetriever	- init

Reading data	- open
	- open:

Setting and retrieving the filename	- filename
	- setFilename:
- directory
- setDirectory:

Assigning delegates	- setDelegate: 
- delegate
- setDataDelegate:
- dataDelegate

Assigning a FileSaver	- set FileSaver: 
- fileSaver

INSTANCE METHODS

dataDelegate
- dataDelegate

Returns the object that utilizes the data from the file.  The FileRetriever must have a dataDelegate which responds to a readDataFromStream: message.

See also:  ± setDataDelegate:

delegate
- delegate

Returns the object that receives the dataWasRead:success:errorCode: message, or nil if there is no delegate.  The delegate is optional.

See also:  ± setDelegate:

directory
- (char *)directory

Returns the full path of the directory containing the data file, or an empty string if no file has been set yet.  

See also:  ± setDirectory:,  ± filename, ± setFilename

filename
- (char *)filename

Returns the name of the data file, or an empty string if no name has been set yet.  This name does not include the path.

See also: ± setFilename:,  ± directory, ± setDirectory

fileSaver
- fileSaver

Returns a pointer to the fileSaver, or nil if there is not an associated FileSaver.  The FileRetriever will send the fileSaver setFilename: and setDirectory: messages whenever a file is opened and the data retrieved.    

See also:  ± setFileSaver:, setFilename: (FileSaver), setDirectory: (FileSaver)

init
- init

Initializes and returns the receiver, a new FileRetriever instance.  This method initializes filename and directory to the empty string.

open:
- open:sender

Opens a file chosen by the user and requests that the dataDelegate read data from it.   An OpenPanel is displayed to the user to choose a file.  A stream is then opened on the file and the dataDelegate is sent a readDataFromStream: message requesting it to read the data from the stream.  The stream is then closed and the delegate is sent a dataWasRead:success:errorCode message if there is a delegate which implements that method.  The fileSaver, if there is one, is sent the setFilename: and setDirectory: messages.  Returns self.

See also:  ± open

open
- (BOOL)open

Opens the file specified by directory and filename and requests that the dataDelegate read data from it.   The filename and directory must be previously set (either with open: or with the pair setFilename: and setDirectory:).  A stream is opened on the file and the dataDelegate is sent a readDataFromStream: message requesting it to read the data from the stream.  The stream is then closed and the delegate is sent a dataWasRead:success:errorCode message if there is a delegate which implements that method.  The fileSaver, if there is one, is sent setFilename: and setDirectory: messages.  Returns YES if the data was successfully read; otherwise, it returns NO.

See also:  ± open:

setDataDelegate:
- setDataDelegate:anObject

Sets a pointer to the object which will be responsible for reading the data from the opened file whenever the FileRetriever receives an open or open: message.  Returns self.

See also:  ± dataDelegate

setDelegate:
- setDelegate:anObject

Sets a pointer to the object which will receive a dataWasRead:success:errorCode message when the FileRetriever has attempted to a file and have the dataDelegate read from it.  Returns self.

See also:  ± delegate

setDirectory:
- setDirectory:(char *)path

Sets the contents of the directory instance variable.  This message may be sent by an associated FileSaver.  Returns self.

See also:  ± directory,  ± filename,  ± setFilename:

setFilename:
- setFilename:(char *)name

Sets the contents of the filename instance variable.  name should be the name of the file and should not include the path to the file.  This message may be sent by an associated FileSaver.  Returns self.

See also:  ± filename,  ± directory,  ± setDirectory:

setFileSaver:
- setFileSaver:anObject

Sets a pointer to an instance of FileSaver.  fileSaver will be sent setFilename: and setDirectory: messages whenever a file is open and the data retrieved.  Returns self.

See also:  ± fileSaver

METHODS IMPLEMENTED BY THE DELEGATE

dataWasRead:success:errorCode:
- dataWasRead:sender success:(BOOL)flag errorCode:(int)code

This message notifies the delegate whether or not the FileRetriever has successfully opened the file and had the dataDelegate read the data from the file.  Error codes are listed below.  Returns self.

readDataFromStream:
- (BOOL)readDataFromStream:(NXStream *)stream

This message requests the dataDelegate to read its data from stream.  This method is called from the open: and open methods of FileRetriever.  This method should return YES if the dataDelegate was able to read the data and NO if it was not.

CONSTANTS (defined in SaverAndRetriever.h)

	noStream 			= NX_APPBASE,
	noDataDelegate 		= NX_APPBASE+1
	doesNotRespondToMethod 	= NX_APPBASE+2
	cancelButtonPushed 		= NX_APPBASE+3
	dataNotWritten 		= NX_APPBASE+4
	dataNotRead 			= NX_APPBASE+5
	unableToSaveStreamToFile 	= NX_APPBASE+6
	noFile 			= NX_APPBASE+7
	noError 			= NX_APPBASE+8