|
OPP Preliminary Documentation
OPP is based on the functionality found in the Java class libraries,
the Rogue Wave libraries, in the class libraries that came with
ht://dig version 3.08b2 and from my own twisted ideas. Its goal is to
grow into a full fledged general purpose C++ class library with a
level of functionality at least that of the Rogue Wave class
libraries.
OPP is currently in development. The code is in places stable enough
to be used for real applications, and in fact is. However, it is
incomplete, inconsistent, poorly tested and the interface is subject
to incompatible change at any moment. Beware!
Building OPP
To build OPP, you must use a modern C++ compiler such as gcc 2.95.2 or
egcs 2.91.66 and a modern operating system with Posix threads support
such as Linux. OPP 0.2.5 probably does not work with gcc 3.
For now, you must modify config.h to identify the flags and location
of your compiler. The defaults are appropriate for building with
optimization using gcc or egcs installed as /usr/bin/gcc
and /usr/bin/c++.
OPP requires GNU make and uses an automagic dependency calculator
derived from the GNU make documentation. This dependency calculator
has three problems and will be removed or fixed in a future release.
The problems are: 1. Leaves the source directories filled with '*.d'
files. 2. The build fails with an error if an include file is deleted
or renamed and at least one '.d' file still references it. Even a
'make clean' will fail when this happens. 3. It can sometimes lead to
what appears to be an infinite loop. This can happen when a tar file
of the source code is created and moved from one machine to another
with a different system time. Make will continue to remake the
dependencies because it continues to believe that they are out of date
(the timestamp on the source code is newer than the system time). The
loop will eventually terminate when the system time hits the source
code timestamps.
You can do 'make' to make the library, and 'make install' to 'install'
it (to the opp/lib subdirectory).
Testing OPP
Several of the OPP 'packages' include test suites. The current test
suites are in
Base/String/Parser/test
Database/Space/test
Document/test
IO/Net/test
Template/test
Any one of the tests can be performed by the commands cd DIR;make test
Directory structure and class description
Base/
Basic classes.
Object
An Object provides virtual methods for copying,
serializing and deserializing, hashing, converting to
a (printable) string and comparisons. A first class
Object subclass will provide all object methods and
register with the Object Registry for generic
serializing/deserializing. Object behavior is
implemented using public and protected methods.
Object also provides convenience comparison operator
overloads that use the protected comparison methods
and a hash function for use by template containers.
Most OPP classes are subclasses of Object. Not all
OPP Object's are first class Object's. The only OPP
classes that are not Object's are the template classes
and simple classes with specific transient purposes;
e.g. Exception. Template classes are not Object's
because virtual methods lead to inefficient code
generation when used with templates.
Integer
A first class Object wrapper for signed integers.
Integer also provides hash functions for all built in
integer types.
Double
A first class Object wrapper for double precision
floating point values. Double also provides hash
functions for floating point types.
Exception
A base class for all exceptions thrown by OPP.
Exceptions are not (OPP) Object's. An exception will
include a null terminated character message.
ReferenceCounted
A base class for counting references to allocated
objects. ReferenceCounted is not an Object. It is
intended to be used as another base class for Objects
(in multiple inheritance) or by stand-alone classes.
ReferenceCounted is implemented as a template called
TReferenceCounted the accepts a lock type as a
parameter. The ReferenceCounted typedef uses the
NoLock class.
Some classes that are ReferenceCounted: String,
StringBuffer, fdStream, Enumeration.
LockingReferenceCounted
A thread-safe version of ReferenceCounted that is
equivalent to TReferenceCounted.
RCPointer
A container for implementations of the
ReferenceCounted class. An RCPointer can be allocated
on the stack or as an instance variable in some other
object and will automatically add and delete
references to the contained object. RCPointer
provides methods that make it work like a regular C
style pointer. RCPointer is not an Object.
Registry
The ugly hack that allows OPP to serialize and
deserialize arbitrary Object's. Can be used in
conjunction with ObjectReader and ObjectWriter (IO
library) to implement a poor man's CORBA-like
environment. Will eventually be used by the Object
Database, when it is written.
An arbitrary Object can be serialized using
SerializeObject. This will produce a byte stream that
can be passed to DeserializeObject to reconstitute
what is functionally the exact same Object. Note:
this is true only for Object's that implement
Serialize and Deserialize and have registered with the
Registry.
Registry uses rcc to convert Registry-ID into
Registry-gen.H and Registry-gen.cc which are then
included in Registry.H and Registry.cc. Registry-ID
is a list of class names of Object subclasses and the
object ID associated with the class. It is used only
for OPP built in classes. These ID's are meant to be
assigned on a permanent basis.
A class registers with Registry in three ways: (1) add
entry to Registry-ID. (2) include
declareSerializable(class) in class interface
specification. (3) implement Serialize() and
Deserialize() Object methods.
Application defined Object subclasses can also
register by following three steps: (1) choose an
object ID from the set of those reserved for
applications (integers from APPLICATION_CID up). (2)
include declareExternalSerializable(class,id) in class
interface specification. (3) implement Serialize()
and Deserialize() Object methods.
Serializer
A class that collects a byte stream of objects
(including simple types, Object's and other classes)
that are serialized. Each new object is appended to
the byte stream. Serializer will serialize simple
types in network byte order. Complex types, which are
responsible for providing their own serialization
routines, will be platform independent if they use the
Serializer primitives to serialize all their instance
variables. Serializer returns a byte stream in the
form of a String. All OPP Serializable classes are
serialize in a platform-independent way.
Deserializer
Deserializer will reconstitute to specific objects the
contents previously stored to a byte stream by
Serializer. Deserializer must be called with the same
sequence of objects as was used with Serializer to
create the byte stream.
BinaryTreeNode
This class structurally implements a red-black binary
tree. It is used by Template/BinaryTree. It's included
here because it needs to be linked in whenever a
BinaryTree template is used, but is not itself a template.
EnumerationData
Base class for all TEnumerations. It's included here
because it needs to be linked in whenever a BinaryTree
template is used, but is not itself a template.
Utility/DateTime
A class capable of parsing 'arbitrary' date formats,
for suitably restrictive values of arbitrary.
DateTime has been tested on all standard internet date
formats, but is unlikely to work on dates found
embedded within arbitrary text. In particular,
DateTime does not recognize time zone names
(e.g. "EST") and cannot recognize the mm/dd/yy numeric
date format unless specifically told to look for it.
DateTime is quite reliable for parsing dates found in
EMail, HTTP or HTML headers and is used extensively
within the Index of Alternative Operating Systems for
this purpose.
At some future time, DateTime will add the ability to
parse dates according to a 'script'. This capability
is considered low priority, since the strptime() C
library function already does this.
Base/String/
Part of the Base library. Provides String and StringBuffer.
These classes are like the Java classes of the same names but
with additional functionality (and some missing
functionality). String and StringBuffer currently have
completely different implementations - even though much
functionality is common. This will eventually be merged into
a common base class to which String and StringBuffer will be
but two of many possible interfaces. There will also be some
sort of integratation with the standard C++ library's string
class.
String
An immutable string. The contents of the String are
kept as a ReferenceCounted object. String is a first
class Object.
StringBuffer
A mutable string. The contents of the StringBuffer
are kept as a ReferenceCounted object. StringBuffer
will allocate additional space beyond the size of the
string in anticipation of future growth. StringBuffer
is a first class Object.
Caution: StringBuffer has copy constructor and
assignment operator that perform different actions.
The copy constructor keeps a pointer to the original
contents and adds a reference. The assignment
operator actually creates a new buffer and copies the
data from the old one. The difference: for both cases
call the old StringBuffer A and the new StringBuffer
B. If B is created using a copy constructor from A,
then a modification to the contents of B will also
modify the contents of A and vice versa. This is
convenient (and fast) for pass-by-value function call
and return. If B is created by assignment from A,
then a complete new copy of the contents is created
and modifications to B will have no effect on A and
vice versa.
This difference actually makes some sense and would
work well if C++ were a well constructed programming
language. Unfortunately, for some baffling reason,
the code 'StringBuffer B=A;' actually calls the copy
constructor to create B from A, instead of using the
assignment operator.
The real solution is impossible: provide both
'shallow' and 'deep' versions of the copy constructor
and assignment operator. I want both behaviors to be
available, since there are advantages to each.
The other solution is copy-on-write; which is possible
but places restrictions on the StringBuffer interface
and affects performance of simple operations.
Note that String doesn't have this dichotomy. Since a
String's contents cannot be changed the reference
counting method is used for both copy constructor and
assignment operator.
Base/String/Parser/
Part of the Base library. Classes used for parsing. Very
sparse. Includes only classes with functionality similar to
ht://dig. Additions should include standard parsing and
matching tools such as lexers and regular expressions.
StringMatch
A simple string matcher that can match an input string
to one or more pattern strings. Does not support
wildcards or regular expressions of any kind, but does
support optional case insensitivity.
SubstitutionString
A template parser that substitutes variable
definitions recursively into a text template (e.g. a
variable definition can refer to other variables).
SubstitutionString supports simple variable
substitution and function calls to other templates.
Matcher
Matches abbreviations and proper names. Returns a
number indicating the relative likelihood of a match.
Intended to be used to choose the best known match for
an abbreviation or form of name from a list of
possibilities. In particular, Matcher is intended to
match company names and abbreviations to a list of
names.
Base/Thread/
Part of the Base library. This may be made optional, and
there will be two versions of each class - a thread safe
version and a non-thread safe version. There will be two of
each library - a thread library and a no-thread library. The
thread library will include both versions of each class.
No class in the thread library is a first class Object and
none support serialization.
The Thread library is modelled in part after Java threads. It
will be extended over time to include all functionality found
in Threads.h++ from Rogue Wave.
Condition
Condition variable. A thread may signal the condition
or block until the condition is signalled. The
condition variable also operates as a mutex.
Mutex
A mutual-exclusion lock that is a thinly veiled
layer over Posix mutexes.
RCMutex
A reference counted implementation of Mutex. Required
to allow multiple Condition variables to share a
single underlying Mutex. There may be other cases
where a shared Mutex is desired, but none within OPP.
Note: This implementation of RCMutex has not been
tested. It uses a TReferenceCounted instance
to provide both the reference counting and the mutex
locking. This will lead to a deadlock if the Mutex is
copied or released while locked by the same process.
It will be rewritten at a later date to prevent this.
RecursiveMutex
A mutual-exclusion lock that allows itself to be
recursively locked by the same thread. On operating
systems in which it is supported, RecursiveMutex is
implemented using an extension to standard mutexes;
otherwise an implementation is built on top of the
standard mutex.
SpinLock
Similar to a Mutex, but intended to be held only for
short periods of time. SpinLocks are efficient only
if there is a statistically very small chance that
there will be a conflict between processes for the use
of the lock. When appropriate, a SpinLock is much
faster than a Mutex.
SpinLocks are only available for x86 and SPARC and
only if gcc is used. Additional locks will eventually
make there way in.
NoLock
Exactly as the name implies, this class does no
locking; but implements the same interface as all
other locks. This allows the use of a template
parameter to specify a particular locking style.
Lock
A traditional read/write style lock. Supports read
lock promotion (dangerous! - can lead to deadlock).
LockSet
Grabs an entire set of locks at once. This is NOT
guaranteed to be an atomic operation, so the calling
code must be prepared to check the state of any
invariants after the call succeeds. LockSet is
guaranteed to never deadlock (when used with other
LockSets) - however, it is possible to thrash for an
arbitrary amount of time (the locks will eventually be
granted).
Rendezvous
Waits for N threads to reach the point before allowing
any of the threads to continue at which point all
threads continue and the counter is reset to zero.
Runnable
An interface used by Thread to call a method of a
Runnable subclass and run that method in a new thread.
SmartLock
A traditional read/write style lock that tracks thread
id's and provides enhanced write lock blocking. A
regular Lock will allow new read locks following a
write lock request. SmartLock will not (but will wait
for existing reads to complete). SmartLock also has
some other neat features - for instance, if you call
addExclusive(false) to promote a read lock and you get
the lock then you are guaranteed that no other write
occurred on the object. If you don't get the lock,
then you maintain your read lock and have avoided a
deadlock. Promotion of read locks to write locks
happens automatically when a write lock is requested
(dangerous!). SmartLock is recursive - even across
any combination of read and write lock requests.
Synchronize
A stack based object wrapper around a Lock, Mutex or
SmartLock. Synchronize will grab either a shared or
exclusive lock on a Lock when it is instantiated and
release the lock when it is destructed.
Thread
A simple Object wrapper around starting and managing
Posix threads.
ThreadAttributes
A simple Object wrapper for setting attributes for a
thread.
ThreadCounter
Counts threads assigned to a particular task and
prevents additional threads from being created if a
maximum number is exceeded (also allows the caller to
time out and continue anyway). ThreadCounter is
designed to allow servers which create a thread per
connection to have performance that degrades more
gracefully once a high load is reached.
ThreadPool
Manages a pool of threads to which tasks can be assigned.
Idle threads are maintained in the pool for quick response
to available tasks. Tasks are performed by assigning
Runnable actions to the pool.
PCQueue
A producer-consumer queue for thread communication.
Supports any number of producer threads (threads that
push messages onto the queue) and any number of
consumer threads (threads that pop messages off of the
queue).
Note: not tested as written - a version using STL
collections has been tested and works, but the OPP
version has not been.
Base/Collection/
Classes to hold collections of Object's. See also: Template/
Object Collections have some important advantages for holding
Objects over a template collection holding pointers to
Objects. Most important is that an Object Collection is
itself a first class instance of Object. The template
collections are not Object's at all.
The Object Collections are currently implemented with a completely
separate code base from the template collections. Eventually (soon,
actually), the Object Collections will be re-implemented using
the template collection to implement functionality.
Association
An Association associates a key with a value.
AssociationList
A list of key/value pairs in the form of Associations.
An AssociationList is a subclass of KeyedCollection
and is appropriate for small, unordered collections.
CharDictionary
Keyed Collection that maps (char *) to Object and
stores keys in a hashtable. Meant to replicate the
functionality of Dictionary in ht://dig.
Collection
Abstract base class for all Object collections.
Defines a set of virtual methods that each subclass
must implement.
Dictionary
Keyed Collection that maps Objects to Objects and
stores keys in a hashtable.
ObjectEnumeration
Like Java's Enumeration class.
EnumerationData
Base class for enumeration implementations.
Hashtable
A Collection that stores Objects in a hashtable.
Provides fast lookup by value.
KeyedCollection
Abstract base class for all Object collections mapping
keys to values. Defines a set of virtual methods that
each subclass must implement.
List
A Collection that stores Objects in a doubly linked
list. List provides a superset of the Collection
functionality and is used to implement several other
collections.
Queue
A Collection that stores Objects in a FIFO doubly
linked list.
SortedList
A Collection that stores Objects in sorted order in a
doubly linked list.
Stack
A Collection that stores Objects in a LIFO doubly
linked list.
StringList
A Collection that specifically holds String Objects.
StringList provides additional constructors and
parsers for converting text to a list of Strings.
Meant to replicate functionality needed by ht://dig.
ListException
Defines the ListEmptyException thrown when an
operation that requires at least one element to be in
the list is run on an empty list.
IndexOutOfBoundsException
A standard exception to be thrown when an index
exceeds bounds.
NullPointerException
A standard exception to be thrown when an attempt is
made to dereference a NULL pointer
Base/Utility/
A collection of utility functions used by OPP. The functions
may or may not be natively available on your platform. OPP
will use the native function if available or its own, if not.
Currently contains an implementation of timegm.
Database/
The beginnings of the OPP Object Database. Currently empty!
Database/Space/
Part of the Database library. Manages blob allocation and
caching within a Space (such as a file, memory or any other
seekable medium).
At one point, this library - used in conjunction with a
secondary indexing algorithm - outperformed GDBM by as much as
a factor of 10 for storing and retrieving indexed blobs in a
disk file and produced files using about half the space on
average. However, it is expected that the recent
'threadification' of the library has negatively impacted its
performance (the file size should still be small). Over time,
its performance will improve again as the threading
architecture is reexamined and optimized.
Blob
An abstract reference counted container that can return
a pointer containing either readable or writable memory
that corresponds to the contents of a region of a Space.
SpaceManager
Manages allocation and retrieval of blobs to and from a
Space.
Space
Abstract base class defining an interface to a Space.
fileSpace
Implementation of Space for use with normal files.
smartCache
Used by fileSpace to provide caching. smartCache stores
cache blocks in small thread-specific LRU lists and in a larger
global binary tree.
fileSpaceRead
Error handling wrapper for read.
fileSpaceWrite
Error handling wrapper for write.
IO/
IO classes. The architecture is horrible. The internals are
decent. All IO classes are Object's, but none are first
class. No IO Object is serializable.
IOException
Base class for all IO Exceptions. Exceptions are used
liberally by the IO library.
Stream
Abstract base class for all IO classes.
InputStream
Abstract base class for input streams (reading).
Defines high level methods for accessing data and low
level virtual methods for implementation. InputStream
automatically buffers input.
OutputStream
Abstract base class for output streams (writing).
Defines high level methods for outputing data and low
level virtual methods for implementation.
OutputStream does not buffer output.
SeekableStream
Abstract base class for streams supporting repositioning.
fdStream
Base class for all streams that are accessed through
UNIX file descriptors. These streams are the only
ones currently implemented. It is intended that some
higher level interface to various types of file
descriptors will be made available (e.g. regular file,
socket, etc.). Of the various types of file
descriptors, only sockets have a higher level
interface (in IO/Net/).
FileStream
An implementation of fdStream with methods to
manipulate disk files. FileStream currently only has
methods to open files. Other manipulations will be
added (e.g. delete, rename, etc.)
fdInputStream
Implementation of InputStream for file descriptor
streams. This class inherits from both fdStream and
from InputStream. This turns out to be a bad idea in
the way that C++ handles constructors. Subclasses of
fdInputStream have to be careful to explicitly
construct the fdStream AND the InputStream despite the
fact that fdInputStream apparently does so on its own.
This breakage will be fixed in a future
rearchitecture.
fdOutputStream
Implementation of OutputStream for file descriptor
streams. This class inherits from both fdStream and
from OutputStream. This turns out to be a bad idea in
the way that C++ handles constructors. Subclasses of
fdOutputStream have to be careful to explicitly
construct the fdStream AND the OutputStream despite
the fact that fdOutputStream apparently does so on its
own. This breakage will be fixed in a future
rearchitecture.
fdIOStream
A file descriptor stream that allows both input and
output. This class inherits from all of fdStream,
InputStream and OutputStream. This turns out to be a
bad idea in the way that C++ handles constructors.
Subclasses of fdIOStream have to be careful to
explicitly construct the fdStream, InputStream AND the
OutputStream despite the fact that fdIOStream
apparently does so on its own. This breakage will be
fixed in a future rearchitecture.
fdSeekableStream
Base class for file descriptor streams that allow
repositioning.
fdSeekableInputStream
Implementation of fdInputStream that's also an
fdSeekableStream. See earlier rants about multiple
inheritance.
fdSeekableOutputStream
Implementation of fdOutputStream that's also an
fdSeekableStream. See earlier rants about multiple
inheritance.
ioWaiting
Defines an ioWaiting abstract base class for
asynchronous I/O. ioWaiting has virtual methods to
handle I/O events (timeout, ready and error). Also
defines abstract fdInputWaiting and fdOutputWaiting
classes which inherit from both an fdStream and
ioWaiting.
Users of ioWaiting will subclass ioWaiting (or
fdInputWaiting/fdOutputWaiting) and implement the
virtual methods as appropriate for the task.
fdSelect
Interface to select. Accepts fdInputWaiting or
fdOutputWaiting instances. The interface is based on
abstracting asynchronous I/O. However, neither the
async I/O support nor the interface have been
completed.
fdSelect accepts any number of streams with elaborate
per-stream timeout processing.
TimedReader
A wrapper that uses fdSelect and fdInputWaiting to
implement timeouts on a single input stream.
TimedWriter
A wrapper that uses fdSelect and fdOutputWaiting to
implement timeouts on a single output stream.
StringStream
An InputStream, OutputStream and SeekableStream based
on StringBuffer.
ObjectReader
Reads an Object from an InputStream and reconstitutes
the Object using Registry.
ObjectWriter
Serializes and writes an Object to an OutputStream.
IO/Net/
Part of the IO library. Network classes that work with sockets.
EMail
Process and/or send electronic mail messages. Can
parse single messages and 'digests' or mailboxes
containing multiple messages in standard EMail
formats. Sends mail using sendmail or other
compatible external transport program. Allows access
to EMail headers using an AssociationList.
URL
A wrapper class encapsulating a URL. Not yet an Object.
It will be made into one.
DocumentServer
Defines an abstract interface for accessing documents
on remote servers. DocumentServer provides a way to
construct an appropriate concrete instance from a
given URL. Available subclasses are HTTP, FTP and
File.
HTTP
Perform transactions on an HTTP server. The HTTP
class supports most HTTP transactions and understands
HTTP version 1.1. This is the first release of the
HTTP class, so not all features are complete or
tested. In particular, PUT is not supported.
FTP
Perform transactions on an FTP server. The FTP class
supports only the GET operation at this point.
File
Perform transactions on a local file through the
abstracted DocumentServer interface.
InetAddress
Abstracts an entire internet address (host and
service). Basically a container for InetHost and
InetService.
InetHost
Abstracts the host part of an internet address
including whether the host was specified by name or
address. Automatically looks up the missing
information when needed. A lookup cache is kept and
the maximum number of entries and age limits can be
set using static methods.
InetService
Abstracts the service part of an internet address
including whether the service was specified by name or
port number. Automatically looks up the missing
information when needed.
InetHostName
Container for the host name of an internet address.
Contains methods to explicitly look up the
corresponding IP address.
InetHostAddress
Container for the IP address part of an internet
address. Contains methods to explicitly look up the
corresponding host name.
InetServiceName
Container for a service name. Contains methods to
explicitly look up the corresponding port number.
InetServicePort
Container for a service port number. Contains methods
to explicitly look up the corresponding service name.
Socket
Base class for all socket classes. Handles such
generic tasks as open and close of the socket and
setting socket options. Socket also provides Object
methods. A Socket is an fdStream.
ClientSocket
Implementation of Socket specialized for use in client
applications. Provides methods for connecting to a
server. Once connected, a ClientSocket should be used
to construct some sort of fdIOStream, fdInputStream or
fdOutputStream for actual communications.
ServerSocket
Implementation of Socket specialized for use in server
applications. Provides methods for binding, listening
and accepting connections from clients. Returns a
Connection object for each client connection. An
fdInputStream can be constructed from the ServerSocket
and placed in fdSelect. fdSelect will notify when a
connection has arrived.
Connection
Subclass of fdIOStream specialized for being a network
connection. Provides a method for obtaining
information about the remote system.
Cookie
Class that encapsulates an HTTP cookie. Maintains the
data in the cookie. Can parse the cookie from HTTP
data or output the cookie into HTTP format for sending
to a server or client.
More cookie handling will be coming soon.
MimeTypes
Interface for converting file extensions to mime
types. Depends on the existence of the
/etc/mime.types file.
_ClosingClientSocket
Class that automatically closes an fdStream when it
goes out of scope. Was private to HTTP, but made into
a separate file for sharing. Can be used on any
fdStream, not just client sockets but continues to
have a poorly chosen name. This class will be renamed
in OPP 0.3.
NetException
Base class for all exceptions thrown by the Network
library.
Template/
The template classes hold collections of elements. Template
classes can hold both 'element' and 'pointer to element'
types. Template classes holding 'pointer to element'
automatically manage the memory associated with the element.
See also: Collection/
Many of the template classes have .C files for method
implementation. This is strictly a semantic distinction - the
.H file invariably #include's the .C file.
Template classes are currently prefixed with 'T'. This is to
prevent name conflicts with the Object collections to allow
easy porting of ht://dig to the new library. This will change
in a future release (the Object collections will likely be
placed in their own namespace).
Examples of template usage:
TList list_of_ints;
TList list_of_int_pointers;
TListP managed_list_of_int_pointers;
The first two lists hold 'elements'. The last list holds
'pointers to element' and manages the memory of 'elements' (in
this case ints) placed in the list. The list_of_int_pointers
does not support comparisons to int and does not manage
the memory associated with pointers placed in the list. The
managed_list_of_int_pointers does both.
All template convenience types are available in two forms:
regular and pointer. The pointer convenience types will have
a 'P' suffix to specify pointer management.
Template collections are divided into three basic types. The
three basic types are Collection, OrderedCollection and
HashedCollection. Each of these types can store just values,
or key/value pairs. OPP defines convenience types for defining
instances of all of these collections.
Unfortunately, there is no way in C++ to enforce an interface
on the implementation of a Template class. The standard way
to do so in C++ is to use virtual methods in an abstract base
class. This doesn't work well with templates since the
compiler is forced to generate code for all virtual methods
whether or not the method is ever used. Most compilers will
not generate code for a normal method in a template class that
is never called.
A formal interface could be used to enforce that a template
class or subclass follows the specification. It could also be
used for documentation and reference purposes (e.g. the
key-value sub-types are all defined as templates that accept
an implementing type of regular collection as a parameter - it
would be nice in the documentation to say: requires a template
that implements the HashedCollection interface).
The convenience types supported by OPP are:
TList
A doubly linked list holding elements of type
VALUE. Comparisons use operators based on
VALUE.
TSList
A singly linked list holding elements of type
VALUE. Comparisons use operators based on
VALUE.
TBinaryTree
A red-black binary tree holding elements of
type VALUE. Comparisons use operators based
on VALUE.
THashtable
A hashtable holding elements of type VALUE.
Comparisons use operators based on VALUE.
TQueue
A queue holding elements of type VALUE.
Comparisons use operators based on VALUE.
TStack
A stack holding elements of type VALUE.
Comparisons use operators based on VALUE.
TLRUCache
A Least Recently Used cache holding elements
of type (VALUE *). Comparisons use operators
based on VALUE.
TLRUHashtable
A Least Recently Used cache holding elements
indexed using a hashtable. Only the most
recently accessed values are kept in the
table. The least recently used entry is
dropped on insert when the maximum size is
reached.
TSortedList
A doubly linked list always kept in smallest
to largest order holding elements of type
VALUE. Comparisons use operators based on
VALUE.
TAssociationList
A doubly linked list holding elements of type
TAssociation. Comparisons use
operators based on KEY.
TAssociationTree
A red-black binary tree holding elements of type
TAssociation. Comparisons use
operators based on KEY.
TDictionary
A hashtable holding elements of type
TAssociation. Comparisons use
operators based on KEY.
TLRUDictionary
A dictionary holding only the most recently
used items. Lookup is performed by KEY.
In addition, OPP supports variations ending with P or RC
(e.g. TListP or TSListRC) supporting automatic
pointer and reference counted pointer management within the
collection.
BinaryTree
An ordered collection with elements stored in a
red-black binary tree. The red-black property is
maintained using non-template code found in
BinaryTreeNode (in libBase.a).
BinaryTree implements the (non-existent)
OrderedCollection interface.
Hashtable
An unordered collection with elements stored in a
hashtable. Requires elements for which opp_Hash is
defined. Base/Integer.H defines this function for
integer types, Base/Double.H defines it for floating
point types and Base/String/String.H defines it for
(char *) types. Base/Object.H includes a definition
suitable for all Object's providing they implement the
hash() Object method.
Elements must also provide an operator== that
'matches' the opp_Hash() function. Object provides a
suitable operator== for Object's implementing the
Equals() Object method. Integer, Double and String
also provide appropriate operators.
Hashtable implements the (non-existent)
HashedCollection interface.
List
A collection with elements stored in a singly or
doubly linked list. A List is unordered in terms of
element comparisons, but maintains elements in the
order in which they were inserted. It provides
methods to insert new elements at the end, the
beginning or at a specific location in the list.
List supports multiple implementations. This feature
is used for a specific purpose by
Database/Space/smartCache. Two general purpose
implementations are available: DoublyLinked and
SinglyLinked, which are what their names imply.
List implements the (non-existent) Collection
interface.
Queue
Uses List to implement a FIFO.
NOTE: Currently exposes all List methods. Users should avoid any List
methods that modify the contents of the list as these methods will
disappear in a future version.
Stack
Uses List to implement a LIFO.
NOTE: Currently exposes all List methods. Users should avoid any List
methods that modify the contents of the list as these methods will
disappear in a future version.
SortedList
A subclass of List that maintains an ordered collection of
elements (sorted from smallest to largest).
SortedList implements the (non-existent) OrderedCollection
interface.
LRUCache
A subclass of List that maintains elements in LRU order.
LRUHashtable
A subclass of Hashtable that also maintains elements
in LRU order and drops the oldest element on an insert
that exceeds the maximum size.
Association
Associates a key element with a value element
Associations are compared based only on the value of
their keys. Associations can be compared to instances
of the key and to any type for which operator== is
defined on the key and that type.
AssociationCollectionAdaptor
Defines the transformation used to convert a
template class into a template class
using Association's.
AssociationList
Defines TAssociationList and TAssociationListP as convenience
types for using List's with Associations.
AssociationTree
Defines TAssociationTree and TAssociationTreeP as convenience
types for using BinaryTree's with Associations.
Dictionary
Defines TDictionary and TDictionaryP as convenience types for
using Hashtable with Associations.
LRUDictionary
A subclass of Dictionary that also maintains elements
in LRU order and drops the oldest element on an insert
that exceeds the maximum size.
Enumeration
Like Java's Enumeration class, but extended to allow
deleting elements during the course of traversal. The
implementation of Enumeration is halfway between the
Java Enumeration and STL's iterator. In the future,
it will be extended further in the iterator direction.
HeapSort
Two template functions for sorting arrays of elements
using the Heapsort algorithm. One function fills and
modifies an array of indices into the original array.
The other sorts in place an array of pointers to elements.
Even though its average case runtime is somewhat slower
than QuickSort, HeapSort is preferred in some instances
because its worst case runtime is identical to its average
case runtime.
Document/
A framework for parsing documents. This is a proof of concept
implementation suitable for parsing HTML 3.2.
The Document framework is capable of interpreting documents in
the same way that a human can because it understands the
effect of layout and format on the visibility and importance
of information to human readers.
Document
Abstract base class providing an interface for parsing
documents. Subclasses of Document provide the
specific knowledge of a particular document format and
convert from that format into a nested series of
generic elements.
Once finished, Document can be used to accurately
convert one document format to another because it
maintains at a high level the visual appearance of the
underlying document.
Element
Defines an interface for elements that can appear in
a structured document. There is a standard set of
Elements defined that reasonably span all parsable document
types.
HTML
Defines a concrete implementation of Document suitable
for parsing HTML 3.2. The parser can function as a
HTML checker, or it can transparently correct
non-standard HTML. In informal testing, this
correction usually has very little affect on the
ability of Netscape to render the resulting document
as intended. However, there were cases where the HTML
was intentionally broken to work around bugs in
Netscape and the "fixed" HTML did not work well.
Markup
Defines the base markup classes intended to span all
document types.
HTMLMarkup
Defines a class to manage the specific processing for
each HTML markup element type. These are usually
subclassed from a base markup class.
PlainText
An implementation of Document for parsing plain text
with paragraphs separated by blank lines.
Visual
Abstract base class for computing (and possibly
displaying) the visual characteristics of the
document.
BlindVisual
This is the only current implementation of Visual. It
computes visibility statistics about the contents of
the document based on its own choice of a standard
screen. Makes a number of "convenient" assumptions
about the affect of various styles and font choices on
visibility.
Translator
Abstract base class for translating text found in documents.
A concrete subclass will implement translation methods
appropriate for the input format (e.g. translating SGML entities
into the corresponding character string).
EntityTranslator
Translates SGML entities into the corresponding
character string. A concrete subclass of Translator.
|
