Creating and Using Settings

3D PLM Enterprise Architecture	Middleware Abstraction	Creating and Using Settings Enabling your clients to save object properties
Use Case

Abstract

This article shows how to create settings and manage them using a setting class.

What You Will Learn With This Use Case
The CAASysLineSetting Use Case
Step-by-Step
In Short
References

What You Will Learn With This Use Case

This use case is intended to show you how to create settings [1] to store persistent object properties, and how to encapsulate their management in a class that makes your clients independent from the actual setting repository management. This is the best way for enabling client applications to access you setting repository.

[Top]

The CAASysLineSetting Case

CAASysLineSetting is a set of use cases of the CAASystem.edu framework that illustrates System framework capabilities.

[Top]

What Does CAASysLineSetting Do

This use case creates a setting class named CAASysLineSetting to manage line object properties: thickness, color, and linestyle. It also shows how a client can access these settings.

[Top]

How to Launch CAASysLineSetting

To launch CAASysLineSetting, you will need to set up the build time environment, then compile CAASysLineSetting along with its prerequisites, set up the run time environment, and then execute the use case [2].

[Top]

Where to Find the CAASysLineSetting Code

The CAASysLineSetting use case is made of a several classes located in the CAASysLineSetting.m module of the CAASystem.edu framework:

Windows	`InstallRootDirectory\CAASystem.edu\CAASysLineSetting.m\`
Unix	`InstallRootDirectory/CAASystem.edu/CAASysLineSetting.m/`

wherwe InstallRootDirectory is the directory where the CAA CD-ROM is installed.

[Top]

Step-by-Step

To create and use settings, there are five main steps:

#	Step	Where
1	Create the setting encapsulating class	CATSysSetting class
2	Initialize the setting attribute values	CATSysSetting class
3	Encapsulate the setting attribute access	CATSysSetting class
4	Encapsulate the setting repository management	CATSysSetting class
5	Use the settings	Client application

[Top]

Creating the Setting Encapsulating Class

The CAASysLineSetting class manages the three setting attributes and the access to the setting repository.

...
class CAASysLineSetting
{
  public:
    CAASysLineSetting();
    virtual ~CAASysLineSetting();
    // Initializing the setting attributes with hardcoded defaults
    HRESULT Init();
  
    // Managing the Thickness attribute
    HRESULT SetThickness(int  iThickness);
    HRESULT GetThickness(int *oThickness);

    // Managing the Color attribute
    HRESULT SetColor(int  iRed, int  iGreen, int  iBlue);
    HRESULT GetColor(int *oRed, int *oGreen, int *oBlue);

    // Managing the Name attribute
    HRESULT SetName(CATUnicodeString *iName);
    HRESULT GetName(CATUnicodeString *oName);

    // Encapsulating the setting repository access
    HRESULT Save();
    HRESULT Commit();
    HRESULT Rollback();

  private :
    static CATSettingRepository *_pSetting;
    CAASysLineSetting(CAASysLineSetting &iCopy);  
};

The CAASysLineSetting class methods and data member are:

`Init`	Initializes the setting attribute values with their defaults
`Setxxx/Getxxx`	Accessor methods for setting attribute values
`Save`	Creates a persistent copy of the memory setting repository in the setting file
`Commit`	Commits setting attribute value modifications, that is, saves them in the memory setting repository while keeping a memory copy of the last setting repository
`Rollback`	Restores the setting repository from the last memory saved setting repository
`_pSetting`	A pointer to the memory setting repository. This pointer must be static to ensure that multiple instances of CAASysLineSetting use the same setting repository, and thus propagate the setting atribute value modifications to any object concerned

Note that the copy constructor is set as private, and is not implemented in the source file. This is to prevent the compiler to implement a public one without you knowing.

[Top]

Initializing the Setting Attribute Values

The setting attribute values must be initialized with their defaults if the persistent setting repository doesn't exist.

HRESULT CAASysLineSetting::Init()
{
  HRESULT hres = S_OK;
  if (NULL ==_pSetting)
  {
    _pSetting = CATSettingRepository::GetRepository("CAASysLineSetting");
    if (NULL != _pSetting)
    {
      long status = 0;
      int Thickness = 1; 
      status = _pSetting->ReadSetting("Thickness", &Thickness);
      if (1 != status)
        hres = S_FALSE;

      if(SUCCEEDED(hres))
      {
        CATUnicodeString Name ("Solid");
        status = _pSetting->ReadSetting("Name", &Name);
        if ((1 != status)
          hres = S_FALSE;
      }
      if(SUCCEEDED(hres))
      {
        int  Color[] = {255,0,0};
        status = _pSetting->ReadSetting("Color", Color, 3);
        if (3 != status)
          hres = S_FALSE;
      }
    }
    else
      hres = S_FALSE;
  }
  return hres;
}

The setting repository is created if it didn't exist previously thanks to the static method GetRepository. If a setting file exists, it is read to initialize the setting attribute values. Then the three setting attribute values are initialized using the ReadSetting method. ReadSetting reads the value from the setting repository if this value exists, and otherwise creates it with the default. This implies that calling Init initializes the setting attribute default values only if these attributes don't exist in the setting repository. Otherwise, their current values are read, and here unused. This also means that Init can't be used to reinitialize the setting attribute values to their defaults.

[Top]

Encapsulating the Setting Attribute Access

The setting attribute access methods WriteSetting and ReadSetting are encapsulated for each setting attribute. Below is the couple of methods for the Thickness attribute.

HRESULT CAASysLineSetting::GetThickness(int *oThickness)
{
  HRESULT hres = S_OK;
  if (NULL == _pSetting)
    hres = Init();

  if (SUCCEEDED(hres))
  {
    // Always use the default value to initialize the object before reading
    *oThickness  = 1;
    long status = _pSetting->ReadSetting("Thickness",oThickness);
    if (1 != status)
      hres = S_FALSE;
  }
  return hres;
}

Methods that access the setting repository should always test the its existence, and initialize it with the default value if doesn't exist. Then the ReadSetting is called with the setting attribute default value.

HRESULT CAASysLineSetting::SetThickness(int iThickness)
{
  HRESULT hres = S_OK;
  if (NULL == _pSetting)
    hres = Init();

  if (SUCCEEDED(hres))
  {
    long status = _pSetting->WriteSetting("Thickness", &iThickness);
    if (1 != status)
      hres = S_FALSE;
  }
  return hres; 
}

Like GetThickness, SetThickness tests the setting repository existence, and initializes it with the default value if doesn't exist. Then WriteSetting writes the attribute value.

[Top]

Encapsulating the Setting Repository Management

To encapsulate the setting repository management, the three methods Save, Commit , and Rollback of CAASysLinesSetting call the SaveRepository, Commit, and Rollback method of the CATSettingRepository class. This makes client applications independent from the actual setting repository, and ensures that all access the same instance of the setting repository.

HRESULT  CAASysLineSetting::Save()
{
  HRESULT hres = S_OK;
  if (NULL ==_pSetting)
    hres = Init();

  if (SUCCEEDED(hres))
    hres =_pSetting->SaveRepository();
  return hres;
}

The setting attribute values are initialized if they were not, and then the SaveRepository method is called. The Commit and Rollback method are identical, except that SaveRepository is replaced by Commit and Rollback respectively.

[Top]

Using the Settings

This is a client application that uses the setting class CAASysLineSetting.

...
  CAASysLineSetting *pSetting = NULL;
  pSetting = new CAASysLineSetting();
  if (NULL == pSetting)
    exit(-1);
  int Red = 0, Blue = 0, Green = 0;          // Retrieve stored or default values
  HRESULT hres = pSetting->GetColor(&Red, &Green, &Blue);
  if (FAILED(hres))
    exit(-1);
  int Thickness = 0;
  hres = pSetting->GetThickness(&Thickness);
  if (FAILED(hres))
    exit(-1);
  CATUnicodeString string;
  hres = pSetting->GetName(&string);
  if (FAILED(hres))
    exit(-1);

  int NewRed = 127, NewBlue = 127, NewGreen = 127;
  hres = pSetting ->SetColor(NewRed, NewGreen, NewBlue);
  if (FAILED (hres))
    exit(-1);
  hres = pSetting->Commit();
  if (FAILED (hres))
    exit(-1);

  NewRed   = 100;
  NewBlue  = 100;
  NewGreen = 100;
  hres = pSetting->SetColor(NewRed, NewGreen, NewBlue);

  int NewThickness = 5;
  hres = pSetting->SetThickness(NewThickness);
  if (FAILED (hres))
    exit(-1);

  hres = pSetting->Rollback();
  if (FAILED (hres))
    exit(-1);

  hres = pSetting->Save();
  if (FAILED (hres))
    exit(-1);

  delete pSetting;
  pSetting = NULL;
...

The application instantiates the setting repository. If it can't be read from a file, it is created in memory and initialized with its default values, that are then read using the Getxxx methods. Then a new color attribute value is set, and the modification is committed, that is stored in a copy of the setting repository. Color and thickness attribute values are modified, but are overwritten by the Rollback of the saved copy when Commit was called. This version of the setting repository is saved to file thanks to the Save method.

[Top]

In Short

This use case shows how to create a class that encapsulates the access to a setting repository that enables client applications to use a unique instance of the setting repository. It also shows how a client application can use this class to set and get the setting attribute values.

[Top]

References

[1]	Setting Repositories and Attributes
[2]	Building and Launching a CAA V5 Use Case
[Top]

[Top]

History

Version: 1 [Mar 2000]	Document created
[Top]

3D PLM Enterprise Architecture

Middleware Abstraction