Source: sysadm/Association.h
|
|
|
|
//
// Association.h
//
// Base class for deriving classes to represent relationships between
// monitored items.
//
//
// 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_ASSOCIATION_H
#define _SYSADM_ASSOCIATION_H
#include <sysadm/Category.h>
#include <sysadm/String.h>
BEGIN_NAMESPACE(sysadm);
typedef CollectionOf<String> StringList;
/**
* An instance of a subclass of Association represents a dynamic collection of
* child Item(s) related to a parent Item identified by a
* selector. For example, the user account Item(s) that are related to
* a group account Item with selector "bar" could be represented by an
* Association. An Association represents an 1-to-n relationship. A
* 1-to-1 relationship is handled as a special case of 1-to-n relationship.
*
* Association derives from Category and supports the same client
* mechanisms for obtaining dynamic information about the Item(s) in an
* Association instance. This class monitors the parent Item and
* subclasses are responsible for determining the child Item(s) that
* added, deleted and changed. The Association class notifies changes
* to listeners.
*
* If an Item with the specified parent selector does not exist, the
* Association will monitor for the addition of an Item with that
* selector. When such an Item is added, the subclasses are notified
* and subclasses can do whatever is necessary to determine the child
* Item(s) at that time and monitor the system for future changes.
*
* If an Item with the specified parent selector existed, but is
* deleted while a client is monitoring the Association, all Items
* are removed from the Association and the Association continues
* monitoring of the system for the addition of an Item with that
* parent selector.
*
* The Association class (Vs. derived classes) is used only when sub-classes
* require logic very specific to the application to determine when
* items are added, changed and removed from the association. For
* example, the relationship may be calculated by queries on a
* database based on "parentSelector". The derived classes
* ComputedAssoc, ChildAttrAssoc and ParentAttrAssoc can be used when
* the data requiring for computing the relationship is contained
* within the Item(s) in the Category(s).
*
* See AssocFactory.h for details on the steps required to plug-in
* an Association.
*/
class Association : public Category {
public:
/**
* Compute the name (selector) for this association instance.
*/
static String computeSelector(const String& parentCategoryName,
const String& parentSelector,
const String& childCategoryName);
/**
* Used internally for logging.
*/
static const char* NAME;
protected:
/**
* Constructor which initializes Category base class with a unique
* name based on the input parameters.
*
* All subclasses of Association must support a
* constructor with this signature which will be called by
* AssocFactory when an instance of Association is requested and
* one does not exist for the specified combination of input
* parameters.
* "parentCategory" is the Category of the parent item.
* "parentSelector" is the Selector of the parent item.
* "childCategory" is the Category of the child item(s).
*/
Association(Category& parentCategory, const String& parentSelector,
Category& childCategory);
/**
* Destructor.
*/
virtual ~Association();
/**
* Starts monitoring the system by registering for notifications
* about the parent Item (identified by "parentSelector" in constructor).
*/
virtual void startMonitor();
/**
* Called if the parent Item (identified by "parentSelector" in
* constructor) is determined to exist in the system at the time
* monitoring is started. Also called if that Item is added later to
* the system. "item" is the parent Item that was added.
* This class provides a trivial implementation.
* Subclasses can override this method to, for example, register
* for notifications on Items in the child Category.
* None of addItem(), changeItem(), orphanItem(), removeItem() or
* replaceItemList() should be called prior to the call
* to parentAdded().
*/
virtual void parentAdded(const Item& item);
/**
* Called when parent Item changes.
* "oldItem" and "newItem" hold the previous and current state of the
* parent Item respectively.
* This class provides a trivial implementation.
* Subclasses can override this method to do whatever is necessary
* to keep the list of child Item(s) up-to-date.
*/
virtual void parentChanged(const Item& oldItem, const Item& newItem);
/**
* Called when parentItem is removed. Removes all Items from its
* list and sends CategoryListener::itemRemoved() messages for
* each child Item to registered listeners.
*/
virtual void parentRemoved();
/**
* Get the parent item of this association.
*/
virtual const Item* getParent();
/**
* Allow ParentCategoryListener to invoke our protected methods.
*/
friend class ParentCategoryListener;
/**
* Get the selector of the parent item.
*/
virtual String getParentSelector();
/**
* Get name of parent category.
*/
virtual String getParentCategoryName();
/**
* Get name of child category.
*/
virtual String getChildCategoryName();
private:
// Compute the name for this association
static String computeAssocName(const String& parentCategoryName,
const String& childCategoryName);
// Intentionally undefined.
Association(const Association&);
Association& operator=(const Association&);
// Opaque implementation.
friend class AssociationImpl;
AssociationImpl* _impl;
friend class AssocFactory;
};
END_NAMESPACE(sysadm);
#endif // _SYSADM_ASSOCIATION_H
Generated by: rusty@irem on Mon Sep 18 18:07:52 2000, using kdoc 2.0a36. |