Source: sysadm/CategoryFactory.h
|
|
|
|
//
// CategoryFactory.h
//
// Factory class for Category objects.
//
//
// Copyright (c) 1998, 2000 Silicon Graphics, Inc. All Rights Reserved.
//
// This program is free software; you can redistribute it and/or modify
// it under the terms of version 2.1 of the GNU Lesser General Public
// License as published by the Free Software Foundation.
//
// This program is distributed in the hope that it would be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
//
// Further, this software is distributed without any warranty that it is
// free of the rightful claim of any third person regarding infringement
// or the like. Any license provided herein, whether implied or
// otherwise, applies only to this software file. Patent licenses, if
// any, provided herein do not apply to combinations of this program
// with other software, or any other product whatsoever.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this program; if not, write the Free Software
// Foundation, Inc., 59 Temple Place - Suite 330, Boston MA 02111-1307,
// USA.
//
// Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
// Mountain View, CA 94043, or http://www.sgi.com/
//
// For further information regarding this notice, see:
// http://oss.sgi.com/projects/GenInfo/NoticeExplan/
//
#ident "$Revision: 1.7 $"
#ifndef _SYSADM_CATEGORY_FACTORY_H
#define _SYSADM_CATEGORY_FACTORY_H
#include <sysadm/Category.h>
BEGIN_NAMESPACE(sysadm);
/**
* CategoryFactory is the factory class for Category objects.
* CategoryFactory methods are mostly used by the Category Service,
* described in sysadmd(1M), to fulfill requests from remote clients.
* They can also be used by any server-side components that require
* information from a Category. Category subclasses will use the
* macros defined here.
*
* To make information about a Category of type "catName" available to
* the rest of the system the following steps are required:
*
* 1. Implement a subclass of Category called "catName".
* - The subclass must have a void constructor. Typically, this calls the
* Category base class constructor with the argument "catName".
* - Use the convenience macro SaCATEGORY_REF_DECL in the header
* file to provide declaration for the routines used by the
* Category Service for obtaining Category instances.
* - In most cases, only one instance of a particular subclass of
* Category should exist in an address space. To enforce this,
* subclasses should protect their constructors and use the
* convenience macro SaCATEGORY_FRIEND_DEF in the class
* declaration in the header file.
* - Use the convenience macro SaCATEGORY_REF_DEF in the c++
* file to provide the definition for the routines used by the
* Category Service for obtaining Category instances. This in
* turn will use the void constructor.
* 2. Create a library called "catName".so.
* 3. Install it in /usr/sysadm/category/
*
* The above steps will allow clients to obtain the Category instance
* for "catName". Category.h describes the different methods
* supported by Category.
*/
class CategoryFactory {
public:
/**
* Static get method. Creates a Category instance for catName, if
* it does not exist. Returns a reference counted Category instance.
*
* The method fails if the Category instance cannot be created.
* On failure, returns NULL and errorString is initialized with
* the localized error string. This can happen if the library
* corresponding to catName cannot be loaded or if the library
* exists but does not define the symbols required.
*/
static Category* getCategory(const String& catName, String& errorString);
/**
* Static release method. Decrements reference count for
* Category instance. Deletes the instance, if there are no
* references to it.
*
* If no error is encountered in uninitializing the internal data
* structures used for creating the Category, returns true.
* Otherwise, returns false and errorString is initialized with
* the localized error string. This can happen if the library
* loaded for creation of the Category instance cannot be unloaded.
*/
static bool releaseCategory(Category* category, String& errorString);
/**
* Used internally for logging.
*/
static const char* NAME;
private:
// Pointer to the object and a reference count.
struct DictElem {
Category* _category;
void* _dso;
int _refCount;
DictElem(Category* category, void* dso, int refCount)
: _category(category), _dso(dso), _refCount(refCount) {
}
};
static DictionaryOf<DictElem> _categories;
};
END_NAMESPACE(sysadm);
/**
* SaCATEGORY_REF_DECL should be used in header files declaring classes
* which are accessed via CategoryFactory. For example:
*
* SaCATEGORY_REF_DECL(ExampleClass);
* class ExampleCategory : public Category {
* ...
* };
*/
#define SaCATEGORY_REF_DECL(className) \
extern "C" NAMESPACE_SCOPE(sysadm)Category* get##className();
/**
* SaCATEGORY_FRIEND_DEF should be used in header files
* within the declaration of classes which
* are accessed via CategoryFactory. For example:
*
* class ExampleCategory : public Category {
* ...
* protected:
* SaCATEGORY_FRIEND_DEF(ExampleClass);
* ...
* };
*/
#define SaCATEGORY_FRIEND_DEF(className) \
friend NAMESPACE_SCOPE(sysadm)Category* get##className(); \
friend class NAMESPACE_SCOPE(sysadm)CategoryFactory;
/**
* SaCATEGORY_REF_DEF should be used in c++ files defining classes which
* are accessed via CategoryFactory. For example:
*
* #include "ExampleCategory.h"
* ...
* SaCATEGORY_REF_DEF(ExampleClass);
* ...
* ExampleCategory::ExampleCategory() {
* ...
* }
* ...
*/
#define SaCATEGORY_REF_DEF(className) \
extern "C" NAMESPACE_SCOPE(sysadm)Category* get##className() \
{ \
return new className(); \
}
#endif // _SYSADM_CATEGORY_FACTORY_H
Generated by: rusty@irem on Mon Sep 18 18:07:52 2000, using kdoc 2.0a36. |