Main Page   Class Hierarchy   Compound List   File List   Compound Members  

XMLPlatformUtils Class Reference

List of all members.

Public Types

Public Types
enum  PanicReasons {
  Panic_NoTransService, Panic_NoDefTranscoder, Panic_CantFindLib, Panic_UnknownMsgDomain,
  Panic_CantLoadMsgDomain, Panic_SynchronizationErr, Panic_SystemInit, PanicReasons_Count
}

Static Public Methods

Initialization amd Panic methods
void Initialize ()
void Terminate ()
void panic (const PanicReasons reason)
File Methods
unsigned int curFilePos (FileHandle theFile)
void closeFile (FileHandle theFile)
unsigned int fileSize (FileHandle theFile)
FileHandle openFile (const char *const fileName)
FileHandle openFile (const XMLCh *const fileName)
FileHandle openStdInHandle ()
unsigned int readFileBuffer (FileHandle theFile, const unsigned int toRead, XMLByte *const toFill)
void resetFile (FileHandle theFile)
File System Methods
XMLCh * getFullPath (const XMLCh *const srcPath)
bool isRelative (const XMLCh *const toCheck)
XMLCh * weavePaths (const XMLCh *const basePath, const XMLCh *const relativePath)
XMLCh * buildLocalPath (const XMLCh *const cacheDirPath, const XMLCh *const hostName, const XMLCh *const filePath)
bool findFile (const XMLCh *const filePath)
unsigned int createDirectory (const XMLCh *const basePath, const XMLCh *const pathName)
bool URLCacheGetEnv (const char *urlEntityCaching)
XMLCh * URLCacheDirGetEnv (const char *urlEntityCacheDir)
Timing Methods
unsigned long getCurrentMillis ()
Mutex Methods
void closeMutex (void *const mtxHandle)
void lockMutex (void *const mtxHandle)
void * makeMutex ()
void unlockMutex (void *const mtxHandle)
External Message Support
XMLMsgLoader * loadMsgSet (const XMLCh *const msgDomain)
Miscellaneous synchronization methods
void * compareAndSwap (void **toFill, const void *const newValue, const void *const toCompare)
Atomic Increment and Decrement
int atomicIncrement (int &location)
int atomicDecrement (int &location)
NEL Character Handling
void recognizeNEL (bool state)
bool isNELRecognized ()

Static Public Attributes

Public Static Data
XMLNetAccessor * fgNetAccessor = 0
XMLTransService * fgTransService = 0

Detailed Description

Utilities that must be implemented in a platform-specific way.

This class contains methods that must be implemented in a platform specific manner. The actual implementations of these methods are available in the per-platform files indide src/util/Platforms .

Member Function Documentation

int XMLPlatformUtils::atomicDecrement (  int &    location )  [static]
 

Decrements a single word variable atomically.

This must be implemented by the per-platform driver. The atomicDecrement subroutine increments one word in a single atomic operation. This operation is useful when a counter variable is shared between several threads or processes. When updating such a counter variable, it is important to make sure that the fetch, update, and store operations occur atomically (are not interruptible).

Parameters:
location Specifies the address of the word variable to be decremented.
Returns:
The function return value is positive if the result of the operation was positive. Zero if the result of the operation was zero. Negative if the result of the operation was negative. Except for the zero case, the value returned may differ from the actual result of the operation - only the sign and zero/nonzero state is guaranteed to be correct.

int XMLPlatformUtils::atomicIncrement (  int &    location )  [static]
 

Increments a single word variable atomically.

This must be implemented by the per-platform driver. The atomicIncrement subroutine increments one word in a single atomic operation. This operation is useful when a counter variable is shared between several threads or processes. When updating such a counter variable, it is important to make sure that the fetch, update, and store operations occur atomically (are not interruptible).

Parameters:
location Specifies the address of the word variable to be incremented.
Returns:
The function return value is positive if the result of the operation was positive. Zero if the result of the operation was zero. Negative if the result of the operation was negative. Except for the zero case, the value returned may differ from the actual result of the operation - only the sign and zero/nonzero state is guaranteed to be correct.

XMLCh* XMLPlatformUtils::buildLocalPath (  const XMLCh *const    cacheDirPath,
const XMLCh *const    hostName,
const XMLCh *const    filePath
)  [static]
 

Utility to join 3 paths

This must be implementd by the per-platform driver and should weave disk cachedir path, the host name and the file path from the URL.

It is an error to have a null disk cachedir path or a null file path.

Parameters:
cacheDirPath The string containing the disk cache directory path
hostName The string containing the host name from the URL
filePath The string containing the filePath from the URL
Returns:
Returns the string containing the woven path. It should be dynamically allocated and becomes the responsibilty of the caller to delete.

void XMLPlatformUtils::closeFile (  FileHandle    theFile )  [static]
 

Closes the file handle

This must be implemented by the per-platform driver, which should use local file services to close the passed file handle, and to destroy the passed file handle and any allocated data or system resources it contains.

Parameters:
theFile The file handle to close

void XMLPlatformUtils::closeMutex (  void *const    mtxHandle )  [static]
 

Closes a mutex handle

Each per-platform driver must implement this. Only it knows what the actual content of the passed mutex handle is.

Parameters:
mtxHandle The mutex handle that you want to close

void* XMLPlatformUtils::compareAndSwap (  void **    toFill,
const void *const    newValue,
const void *const    toCompare
)  [static]
 

Conditionally updates or returns a single word variable atomically

This must be implemented by the per-platform driver. The compareAndSwap subroutine performs an atomic operation which compares the contents of a single word variable with a stored old value. If the values are equal, a new value is stored in the single word variable and TRUE is returned; otherwise, the old value is set to the current value of the single word variable and FALSE is returned.

The compareAndSwap subroutine is useful when a word value must be updated only if it has not been changed since it was last read.

Note: The word containing the single word variable must be aligned on a full word boundary.

Parameters:
toFill Specifies the address of the single word variable
newValue Specifies the new value to be conditionally assigned to the single word variable.
toCompare Specifies the address of the old value to be checked against (and conditionally updated with) the value of the single word variable.
Returns:
Returns the new value assigned to the single word variable

unsigned int XMLPlatformUtils::createDirectory (  const XMLCh *const    basePath,
const XMLCh *const    pathName
)  [static]
 

Create directory for caching the entity files

Parameters:
basePath the absolute path where the fileas are to be cached
pathName The absolute path name where the file is to be cached locally.
Returns:
zero if created directory, else nonzero

unsigned int XMLPlatformUtils::curFilePos (  FileHandle    theFile )  [static]
 

Get the current file position

This must be implemented by the per-platform driver, which should use local file services to deterine the current position within the passed file.

Since the file API provided here only reads, if the host platform supports separate read/write positions, only the read position is of any interest, and hence should be the one returned.

Parameters:
theFile The file handle

unsigned int XMLPlatformUtils::fileSize (  FileHandle    theFile )  [static]
 

Returns the file size

This must be implemented by the per-platform driver, which should use local file services to determine the current size of the file represented by the passed handle.

Parameters:
theFile The file handle whose size you want
Returns:
Returns the size of the file in bytes

bool XMLPlatformUtils::findFile (  const XMLCh *const    filePath )  [static]
 

Checks the existance of a file or directory The input to this function should be fully qualified path

Parameters:
filePath The string containing the absolute path to the file
Returns:
Returns true if the file or directory exists, false otherwise.

unsigned long XMLPlatformUtils::getCurrentMillis (    )  [static]
 

Gets the system time in milliseconds

This must be implemented by the per-platform driver, which should use local services to return the current value of a running millisecond timer. Note that the value returned is only as accurate as the millisecond time of the underyling host system.

Returns:
Returns the system time as an unsigned long

XMLCh* XMLPlatformUtils::getFullPath (  const XMLCh *const    srcPath )  [static]
 

Gets the full path from a relative path

This must be implemented by the per-platform driver. It should complete a relative path using the 'current directory', or whatever the local equivalent of a current directory is. If the passed source path is actually fully qualified, then a straight copy of it will be returned.

Parameters:
srcPath The path of the file for which you want the full path
Returns:
Returns the fully qualified path of the file name including the file name. This is dyanmically allocated and must be deleted by the caller when its no longer needed!

void XMLPlatformUtils::Initialize (    )  [static]
 

Perform per-process parser initialization

Initialization must be called first in any client code.

bool XMLPlatformUtils::isNELRecognized (    )  [static]
 

Return the value of fgNEL flag.

bool XMLPlatformUtils::isRelative (  const XMLCh *const    toCheck )  [static]
 

Determines if a path is relative or absolute

This must be implemented by the per-platform driver, which should determine whether the passed path is relative or not. The concept of relative and absolute might be... well relative on different platforms. But, as long as the determination is made consistently and in coordination with the weavePaths() method, it should work for any platform.

Parameters:
toCheck The file name which you want to check
Returns:
Returns true if the filename appears to be relative

XMLMsgLoader * XMLPlatformUtils::loadMsgSet (  const XMLCh *const    msgDomain )  [static]
 

Loads the message set from among the available domains

The returned object must be dynamically allocated and the caller becomes responsible for cleaning it up.

Parameters:
msgDomain The message domain which you want to load

void XMLPlatformUtils::lockMutex (  void *const    mtxHandle )  [static]
 

Locks a mutex handle

Each per-platform driver must implement this. Only it knows what the actual content of the passed mutex handle is.

Parameters:
mtxHandle The mutex handle that you want to lock

void* XMLPlatformUtils::makeMutex (    )  [static]
 

Make a new mutex

Each per-platform driver must implement this. Only it knows what the actual content of the passed mutex handle is. The returned handle pointer will be eventually passed to closeMutex() which is also implemented by the platform driver.

FileHandle XMLPlatformUtils::openFile (  const XMLCh *const    fileName )  [static]
 

Opens a named file

This must be implemented by the per-platform driver, which should use local file services to open the passed file. If it fails, a null handle pointer should be returned.

Parameters:
fileName The string containing the name of the file
Returns:
The file handle of the opened file

FileHandle XMLPlatformUtils::openFile (  const char *const    fileName )  [static]
 

Opens the file

This must be implemented by the per-platform driver, which should use local file services to open passed file. If it fails, a null handle pointer should be returned.

Parameters:
fileName The string containing the name of the file
Returns:
The file handle of the opened file

FileHandle XMLPlatformUtils::openStdInHandle (    )  [static]
 

Opens the standard input as a file

This must be implemented by the per-platform driver, which should use local file services to open a handle to the standard input. It should be a copy of the standard input handle, since it will be closed later!

Returns:
The file handle of the standard input stream

void XMLPlatformUtils::panic (  const PanicReasons    reason )  [static]
 

The panic mechanism.

If, during initialization, we cannot even get far enough along to get transcoding up or get message loading working, we call this method.

Each platform can implement it however they want. This method is expected to display something meaningful and end the process. The enum indicates why its being called, to allow the per-platform code to display or log something more specific if desired.

Parameters:
reason The enumeration that defines the cause of the failure

unsigned int XMLPlatformUtils::readFileBuffer (  FileHandle    theFile,
const unsigned int    toRead,
XMLByte *const    toFill
)  [static]
 

Reads the file buffer

This must be implemented by the per-platform driver, which should use local file services to read up to 'toRead' bytes of data from the passed file, and return those bytes in the 'toFill' buffer. It is not an error not to read the requested number of bytes. When the end of file is reached, zero should be returned.

Parameters:
theFile The file handle to be read from.
toRead The maximum number of byte to read from the current position
toFill The byte buffer to fill
Returns:
Returns the number of bytes read from the stream or file

void XMLPlatformUtils::recognizeNEL (  bool    state )  [static]
 

This function enables the recognition of NEL char as whitespace chars which is disabled by default. It is only called once per process. Once it is set, any subsequent calls will result in exception being thrown.

Note: Turning this option on will make the parser non complicant.

void XMLPlatformUtils::resetFile (  FileHandle    theFile )  [static]
 

Resets the file handle

This must be implemented by the per-platform driver which will use local file services to reset the file position to the start of the the file.

Parameters:
theFile The file handle that you want to reset

void XMLPlatformUtils::Terminate (    )  [static]
 

Perform per-process parser termination

The termination call is currently optional, to aid those dynamically loading the parser to clean up before exit, or to avoid spurious reports from leak detectors.

void XMLPlatformUtils::unlockMutex (  void *const    mtxHandle )  [static]
 

Unlocks a mutex

Each per-platform driver must implement this. Only it knows what the actual content of the passed mutex handle is.

Note that, since the underlying system synchronization services are used, Xerces cannot guarantee that lock/unlock operaitons are correctly enforced on a per-thread basis or that incorrect nesting of lock/unlock operations will be caught.

Parameters:
mtxHandle The mutex handle that you want to unlock

XMLCh* XMLPlatformUtils::weavePaths (  const XMLCh *const    basePath,
const XMLCh *const    relativePath
)  [static]
 

Utility to join two paths

This must be implemented by the per-platform driver, and should weave the relative path part together with the base part and return a new path that represents this combination.

If the relative part turns out to be fully qualified, it will be returned as is. If it is not, then it will be woven onto the passed base path, by removing one path component for each leading "../" (or whatever is the equivalent in the local system) in the relative path.

Parameters:
basePath The string containing the base path
relativePath The string containing the relative path
Returns:
Returns a string containing the 'woven' path. It should be dynamically allocated and becomes the responsibility of the caller to delete.

Member Data Documentation

XMLNetAccessor * XMLPlatformUtils::fgNetAccessor = 0 [static]
 

The network accessor

This is provided by the per-platform driver, so each platform can choose what actual implementation it wants to use. The object must be dynamically allocated.

Note that you may optionally, if your platform driver does not install a network accessor, set it manually from your client code after calling Initialize(). This works because this object is not required during initialization, and only comes into play during actual XML parsing.

XMLTransService * XMLPlatformUtils::fgTransService = 0 [static]
 

The transcoding service.

This is provided by the per platform driver, so each platform can choose what implemenation it wants to use. When the platform independent initialization code needs to get a transcoding service object, it will call makeTransService() to ask the per-platform code to create one. Only one transcoding service object is reqeusted per-process, so it is shared and synchronized among parser instances within that process.

The documentation for this class was generated from the following files:
Generated on Tue Nov 19 09:36:48 2002 by doxygen1.3-rc1