 Feedback
|
Table Of Contents
Using the Core Client Registry
CCR Local System Data (LSD) Component
Adding an LSD Entry (Installation)
Removing an LSD Entry (Uninstall)
Modifying an LSD Entry (Patching/Upgrading)
Local System Data (LSD) Data Structure
Encrypting and Decrypting CCREntry Values
Using the Core Client Registry
The Core Client Registry (CCR) manages the seamless installation, upgrade, patching and uninstall of Multiple Device Contoller (MDC) modules and the Core module itself.
The following topics describe how to use CCR to manage these tasks:
•
Encrypting and Decrypting CCREntry Values
For more information about CCR, refer to the Core Client Registry Software Unit Design Specification, EDCS ENG-129945.
Understanding CCR
The Core Client Registry:
•
•
•
CCR tracks:
•
•
•
•
•
•
CCR can:
•
•
•
•
•
•
You can access CCR from both C++ and Java applications, usually in the form of a servlet. CCR uses:
•
•
•
•
Note
About the CCR Components
CCR has five major components, which are described in the following topics:
1.
CCR Local System Data (LSD) Component
LSD is the data structure that contains the registration information. It is the repository for all the entries tracked by the CCR. It is in the form of an XML file and is loaded by the CCRprocess. The XML file contains one root element called CCRRoot. CCRRoot will always have an element called resources that contains all of the resources that have been added to an MDC. All of the other elements under CCRRoot are MDCs.
Resources
If any resources are added to CCR, then CCRRoot will have a Resources element. Elements within Resources must adhere to specific rules. Each element is followed by a number that allows differentiation of the resources.
All immediate children of Resources will be called either Library, Custom, ApacheConf, or InitializationInfo followed by a number. For example, Custom1, Library2, ApacheConf5, InitializationInfo7.
These elements are:
•
•
•
•
All other elements under CCRRoot are assumed to be MDC elements:
•
•
•
•
•
All these elements (except for Logging) will contain children that conform to the Resources child element rules (Custom, Library, etc.).
All of these four types of child elements can have the following types of children.
•
•
•
•
These can be changed by privileged users.
The Logging child will have only one of the following elements:
<Location>log_file_name_w_location</Location>However, it can have any number of these elements:
<categoryname priority="priority value"/>Where the priority value can be DEBUG, INFO, WARN, ERROR, FATAL.
CCRProcess Component
This is the heart of CCR. It includes the code that loads the XML file as well as the code that manipulates the elements.
This is the thread that waits for requests to act on the LSD. Upon instantiation, the CCRProcess will either load up the existing LSD into a DOM tree, or if one is not available, it will create a new skeleton LSD that will become the new default one. It also makes backups of the LSD at certain intervals to prevent information from being lost or corrupted. It also creates backups when the LSD has been updated to allow recovery of previous versions if necessary.
There should only be one instance of CCRProcess per process. It uses the sync libraries to prevent deadlocking when multiple CCRInterfaces access the CCRProcess.
CCRInterface Component
The CCRInterface allows modules to modify the data based on their needs (like installation, removal). It is the access point for all CCR functionality. The CCRInterface starts the CCRProcess (if it has not been started already) and it also communicates requests to it. JNI is used to provide the servlets with a means to access the daemon from Java.
C++ client uses a CCRInterface object to interact with the CCR.
Two objects are primarily used with CCRInterface: CCREntry and CCRResponse.
CCREntry Component
Most CCRInterface functions will involve the addition, subtraction, or manipulation of CCREntry objects. These basically contain a list of std::string objects that will allow the CCRProcess to find entries or to properly place the entries with the LSD. It is important to use std::string objects as this will provide for easy translation between Java and C++. CCREntry also provides encryption & decryption capabilities
There are three important fields that help CCR find a CCREntry object within the DOM tree.
•
•
•
CCRResponse Component
This contains the response information for many of the CCRInterface retrieval function calls. It has a Java corollary.
It contains a success value and a vector full of CCREntry objects that were retrieved.
About CCR System Flow
This topic provides an overview of the major functions of CCR:
•
•
•
Adding an LSD Entry (Installation)
The requesting process determines whether or not the CCRProcess has been started.
It creates an CCREntry with the following fields:
•
•
•
•
The CCREntry is passed to the CCRInterace method that handles the addition of entries.
The existing references are searched to determine whether the entry already exists. If it does, it is added, and the resource reference count is incremented. If it does not exist, it is added, and the resource is also added with the new reference and reference count of 1.
Removing an LSD Entry (Uninstall)
The requesting process determines whether or not the CCRProcess has been started.
It creates an CCREntry with the following fields:
•
•
•
The CCREntry is passed to the CCRInterace method that handles the removal of entries. If the resource is referenced by only one rootcomponent, then it is completely removed. Otherwise the resource's reference count is decremented by one and the actual reference of the component below the resource is removed.
Modifying an LSD Entry (Patching/Upgrading)
The requesting process determines whether or not the CCRProcess has been started. The requesting process then locates the entry to be updated. It either creates or is given the entry information.
The entry is updated. First the current entry is removed. If the old entry was the last reference to the resource, that resource is removed.
The existing references are searched to determine whether the entry already exists. If it does, it is added, and the resource reference count is incremented. If it does not exist, it is added, and the resource is also added with the new reference and reference count of 1.
Retrieving an LSD Entry
Pertinent information in the retrieval of the entry is entered into an CCREntry.
The retrieval request is submitted. If the information in the entry correlates to more than one entry in the repository, several entries will be returned in a std::list object. Otherwise the std::list object will only contain one entry. If no entry is found, the std::list object will be empty.
About CCR Data Structures
This topic describes the data structures for the following:
•
Local System Data (LSD) Data Structure
The LSD is an XML document that will contain all of the relevent registration information. There will be a root element which will contain:
•
•
•
All of the leafs of the Core and MDCs will refer to elements within the resources subtree. These include location data, Apache configuration data, library data, initialization data, Java libraries, logging information, notification information, and any custom data that an MDC might need. The resources subtree will maintain the data, location, reference count, and the specific reference of each resource.
Whenever a new resource is to be added to the Core or an MDC, the resource subtree should be checked to see if there is a duplicate resource already available. If the resource is already available, the reference in the Core or MDC branch should point to the existing resource, the reference count of the resource should be incremented and the MDC that is referencing the resource should be added as a child of the resource. Otherwise, a new resource is added and the MDC or Core will point to that.
- <CCRRoot>- <Resources>- <Library1><Name>ite-nosd.dll</Name><Location>c:\ismg\core\libs</Location><ReferenceCount>1</ReferenceCount>- <References><Core /></References></Library1>- <Library2><Name>rulesd.dll</Name><Location>c:\ismg\PIX\libs</Location><ReferenceCount>1</ReferenceCount>- <References><PIX /></References></Library2>- <Library3><Name>configured.dll</Name><Location>c:\ismg\PIX\libs</Location><ReferenceCount>1</ReferenceCount>- <References><PIX /></References></Library3>- <Library4><Name>populated.dll</Name><Location>c:\ismg\PIX\libs</Location><ReferenceCount>1</ReferenceCount>- <References><PIX /></References></Library4>- <Library5><Name>sosd.dll</Name><Location>c:\ismg\PIX\libs</Location><ReferenceCount>1</ReferenceCount>- <References><PIX /></References></Library5>- <Library6><Name>statusd.dll</Name><Location>c:\ismg\PIX\libs</Location><ReferenceCount>1</ReferenceCount>- <References><PIX /></References></Library6>- <Library7><Name>pixd.dll</Name><Location>c:\ismg\PIX\libs</Location><ReferenceCount>1</ReferenceCount>- <References><PIX /></References></Library7>- <Library8><Name>translationd.dll</Name><Location>c:\ismg\PIX\libs</Location><ReferenceCount>1</ReferenceCount>- <References><PIX /></References></Library8>- <Custom1><Name>CustomResourceOne</Name><Location>d:\ismg\core</Location><ReferenceCount>1</ReferenceCount>- <References><Core /></References></Custom1>- <Custom1><Name>CustomResourceTwo</Name><Location>d:\ismg\core</Location><ReferenceCount>1</ReferenceCount>- <References><Core /></References></Custom1>- <Custom2><Name>CustomResourceThree</Name><Location>d:\ismg\core</Location><ReferenceCount>1</ReferenceCount>- <References><Core /></References></Custom2></Resources>- <Core><Location>d:\ismg\core</Location><Configurations /><Libraries />- <ExtensionLibraries><Library1 /></ExtensionLibraries><InitializationInfo />- <Custom><Custom1 /><Custom1 /><Custom2 /></Custom><Java /><Notifications />- <Logging><Location>d:\ismg\core\log\core.log</Location><axiom priority="DEBUG" /><eta priority="DEBUG" /><coreagent priority="DEBUG" /></Logging></Core>- <PIX><Location>d:\ismg\PIX</Location><Configurations /><Libraries />- <ExtensionLibraries><Library2 /><Library3 /><Library4 /><Library5 /><Library6 /><Library7 /><Library8 /></ExtensionLibraries><InitializationInfo /><Custom /><Java /><Notifications /><Logging /></PIX></CCRRoot>CCREntry Data Structure
CCR::CCREntry are strings that contain the information to specify an entry as well as string-based custom key value pairs.
std::string rootelement;std::string subelement;std::string resourcetype;std::string resourcedata;std::string resourcename;std::string resourcelocation;CCRResponse Data Structure
CCR::CCRResponse is a simple data structure that the CCRInterface will return that describes the result of a function execution.
int responsecode;std::string description;std:list<CCREntry*> returnedValues;static final int SUCCESS = 0;static final int FAILURE = 1;static final int EXISTS = 2;Using the CCR C++ API
This topic describes the functions for these components:
For the corresponding Java functions, see the "Using the CCR Java Interface" section.
CCRInterface Functions
The functions and fields of the CCRInterface component are:
Cn::SharedPtr<CCRProcess> theProcess
The process to which the interface will talk.
CCRInterface::CCRInterface()
Creates an interface. The CCRProcess:: StartProcess() function will be called in order to retrieve the process.
CCRInterface::CCRInterface(std::string fileName)
Creates an interface. The CCRProcess::StartProcess(fileName) function will be called in order to retrieve the process.
CCRInterface::CCRInterface(Cn::SharedPtr<CCRProcess> theProcess)
Creates an interface with an already existing process. As the interface should be the only one connecting to the process, this constructor might not be necessary, desired, or needed.
CCRResponse CCRInterface::addEntry(CCREntry* theEntry)
Adds a new entry to the registration repository. If the entry exists, its reference count gets incremented. It takes the following parameters:
theEntry
CCREntry*
The new entry to be added.
Return
CCRResponse
The response to the addEntry request.
CCRResponse CCRInterface::removeEntry(CCREntry* theEntry)
Removes an entry from the repository. If it is the last reference to that entry, it is removed. Otherwise, the reference count is decremented. It takes the following parameters:
theEntry
CCREntry*
The entry to be removed.
Return
CCRResponse
The response to the removeEntry request.
CCRResponse CCRInterface::updateEntry(CCREntry* theEntry, CCREntry* newEntry)
Updates an entry in the repository. It takes the following parameters:
CCRResponse CCRInterface::retrieveEntry(CCREntry* theEntry)
Retrieves the complete info for an entry. It takes the following parameters:
theEntry
CCREntry*
The entry to retrieve.
Return
CCRResponse
The response to the retrieveEntry request.
CCRResponse CCRInterface::retrieveEntriesOfType(CCREntry* theEntry)
Retrieves all entries of the specific type. If there is no rootelement value, it should return the entries from the resources directory. It takes the following parameters:
theEntry
CCREntry*
The entry type to return.
Return
CCRResponse
The response to the retrieveEntriesOfType request.
CCRResponse CCRInterface::applyTomcatConfiguration(CCREntry* theEntry)
Will apply the tomcatconfig entry to the appropriate Tomcat config file. It takes the following parameters:
theEntry
CCREntry*
The entry that describes the proper tomcatconfig.
Return
CCRResponse
The response to the applyTomcatConfiguration request.
CCRResponse CCRInterface::removeTomcatConfiguration(CCREntry* theEntry)
Will remove the tomcatconfig entry from the appropriate Tomcat config file. It takes the following parameters:
theEntry
CCREntry*
The entry that describes the proper tomcatconfig.
Return
CCRResponse
The response to the removeTomcatConfiguration request.
boolean CCRInterface::entryExists(CCREntry* theEntry)
Determines whether or not an entry already exists in the repository. It takes the following parameters:
theEntry
CCREntry*
The entry to examine.
Return
boolean
True if it exists. Otherwise, false.
int CCRInterface::getEntryReferenceCount(CCREntry* theEntry)
Determines the number of reference counts of a particular entry. It takes the following parameters:
theEntry
CCREntry*
The entry to examine.
Return
int
The number of references of the entry.
CCRResponse* CCRInterface::addNotification(std::string mdc, std::string location, std::string protocol)
Adds a notifcation entry to an MDC in the CCR. It takes the following parameters:
CCRResponse* CCRInterface::addMDC(CCREntry* theEntry)
Adds a new MDC to the CCR. It takes the following parameters:
theEntry
CCREntry*
The new MDC to be added.
Return
CCRResponse
The response to the addMDC request.
CCRResponse* CCRInterface::setLoggingLocation(std::string mdc, std::string location)
Sets the location and file name for logging messages within an MDC. It takes the following parameters:
CCRResponse* CCRInterface::addLoggingCategory(std::string mdc, std::string name, std::string priority)
Adds a new category for logging within an MDC. It takes the following parameters:
CCRResponse* CCRInterface::updateLoggingCategory(std::string mdc, std::string name, std::string priority)
Updates a category's priority within an MDC. It takes the following parameters:
std::string CCRInterface::getClassPath(std::string MDCName)
Returns a ";" separated classpath for an MDC. It takes the following parameters:
MDCName
std::string
The MDC that will have its classpath returned.
Return
std::string
A ";" separated list of Java libraries and directories.
std::string CCRInterface::getLibraryPath(std::string MDCName)
Returns a ";" separated path for an MDC's libraries. It takes the following parameters:
MDCName
std::string
The MDC that will have its library path returned.
Return
std::string
A ";" separated list of libraries.
std::string CCRInterface::getExtensionLibraryNames()
Returns a ";" separated list of all of the extension libraries, used primarily for loading purposes. It takes the following parameter:
std::string CCRInterface::getMDCNames()
Returns a ";" separated list of the MDC names within the CCR. It takes the following parameter:
std::string CCRInterface::getMDCLoggingCategories(std::string mdc)
Returns a ";" separated list of all logging categories of an MDC. It takes the following parameters:
mdc
std::string
The MDC that will have its logging categories returned.
Return
std::string
A ";" separated list of of logging categories for an MDC.
std::string CCRInterface::getLoggingLocation(std::string mdc)
Returns the logging location for an MDC. It takes the following parameters:
mdc
std::string
The MDC that will have its logging location returned.
Return
std::string
A MDC's logging location.
void CCRInterface::writeTree()
Writes and saves the CCR.
CCREntry Functions
The functions and fields of CCREntry are:
private std::string rootElement
Describes the root element that contains the entry.
private std::string subElement
Describes the sub element that contains the entry.
private std::string resourceType
Describes the type of the resource.
private std::string resourceData
Describes the data that the resource might contain.
private std::string resourceName
Describes the name of the resource.
private std::string resourceLocation
Describes the location of the resource.
private CustomTagTable customTags
A hashtable that describes any custom keys and values of the resource.
private PasswordTable customPwds
A hashtable that describes the passwords for any encrypted custom keys.
6.
The password for an encrypted data value.
7.
The password for an encrypted location value.
8.
The password for an encrypted name value.
9.
Default constructor that sets all of the values of the entry to "".
10.
Constructor that creates a CCREntry from one that was created to a std::string using the toString method.
11.
Constructor that sets all of the values of the entry to to the argument's values.
12.
Getter function for the root element value.
13.
Getter function for the sub element value.
14.
Getter function for the resource type value.
15.
Getter function for the resource data value.
16.
Getter function for the resource location value.
17.
Getter function for the resource name value.
18.
Getter function for the resource custom tags and values (in a hashtable).
19.
Determines whether the data value has been encrypted.
Return
bool
Indicates whether or not the data value is an encrypted value.
20.
Determines whether the location value has been encrypted.
Return
bool
Indicates whether or not the location value is an encrypted value.
21.
Determines whether the name value has been encrypted.
Return
bool
Indicates whether or not the name value is an encrypted value.
22.
Determines whether the value reference by the key has been encrypted.
key
std::string
The key of the value to be checked.
Return
bool
Indicates whether or not the value reference by the key has been encrypted
23.
Setter function for the root element value.
24.
Setter function for the sub element value.
25.
Setter function for the resource type value.
26.
Setter function for the resource data value.
27.
Setter function for the resource location value.
28.
Setter function for the resource name value.
29.
Setter function for the resource data value encryption password.
30.
Setter function for the resource location value encryption password.
31.
Setter function for the resource name value encryption password.
32.
Returns the number of custom tags in the resource.
33.
Returns the custom key at the index.
34.
Returns the custom value at the index.
35.
Setter for the resource data value. If the password value is not "", then that value is encrypted.
key
std::string
The new resource custom key value.
value
std::string
The new resource custom value.
36.
Converts an entry to a string representation. Used for the JNI interface.
37.
Encrypts the name value.
38.
Encrypts the data value.
39.
Encrypts the location value.
40.
Encrypts the key's value.
key
std::string
The key whose value will be encrypted.
return
int
The length of the string that was encrypted..
41.
Converts a string to an encrypted value based on the password.
toEncrypt
std::string
The string to be encrypted.
password
std::string
The password to the will be the encryption key.
return
std::string
A string representation.
42.
Decrypts a string based on the data password key.
toDecrypt
std::string
The string to decrypt.
size
int
The intended size of the decrypted string.
return
std::string
A decrypted string.
43.
Decrypts a string based on the name password key.
toDecrypt
std::string
The string to decrypt.
size
int
The intended size of the decrypted string.
return
std::string
A decrypted string.
44.
Decrypts a string based on the location password key.
toDecrypt
std::string
The string to decrypt.
size
int
The intended size of the decrypted string.
return
std::string
A decrypted string.
45.
Decrypts a string based on the key's password key.
CCRResponse Functions
The functions and fields of CCRResponse are:
private std::string description
Provide the response's description.
private id responseID
Describes the ID of the reponse. Possible values: SUCCESS, FAILURE, or EXISTS.
std:vector<CCREntry*> returnedValues;
Describes the entry or entries that returned with the response.
static final int SUCCESS = 0;
The ID of a successful response.
static final int FAILURE = 1;
The ID of an unsuccessful response.
static final int EXISTS = 2;
The ID of a response where the entry exists.
CCRResponse::CCRResponse()
Default constructor. The response ID and description are not set; use the setter functions.
CCRResponse::CCRResponse(int type, std::string description)
Constructor that sets the ID and description.
type
int
The response's type. Possible values: SUCCESS, FAILURE, or EXISTS.
description
std::string
The response's description. Explains the type.
CCRResponse::CCRResponse(std::string stringForm)
Constructor that creates a response object from one that was converted into a string.
stringForm
std::string
The representation of a CCRResponse object in a string form.
std::string CCRResponse::getDescription()
The getter function for the description value.
46.
The getter function for the response's type value.
47.
The getter function for the response's returned entries.
std::vector<CCREntry*>
Returns the entries that are part of the response.
48.
The setter function for the description value.
49.
The setter function for the type value.
50.
The setter function for the type value.
values
std::vector<CCREntry*>
The new value of the entries that belong with the response.
51.
The setter function for the type value.
52.
A convenience function that will tell the caller whether the response is a success response or not.
53.
A convenience function that will tell the caller whether the response is a failure response or not.
54.
A convience function that will tell the caller whether the response is a exists response or not.
55.
Converts a CCRResponse object to a string form. Can be reconstituted using the constructor that takes a string as an argument.
Using the CCR API: Example
The following procedure shows how you can use the CCR API to modify and access the CCR.
Step 1
To access and modify the CCR, you must create a CCRInterface object. When this object is constructed, either an existing CCR will be loaded, or a new one will be created.
CCRInterface* theCCRInterface = new CCRInterface();Step 2
In order to create a new MDC, first a CCREntry object should be created where the root element is the name of the MDC, and the location value is where the MDC is located. Then the addMDC method is called on the CCRInterface object.
CCREntry* newMDCEntry = new CCREntry();newMDCEntry->setRootElement("NewMDCName");newMDCEntry->setResourceLocation("d:\mdclocation");theCCRInterface->addMDC(newMDCEntry);Step 3
When the MDC is created, extension libraries pertaining to the MDC must be added. They are located in the MDC element and under the ExtensionLibraries element. The name of each entry will be the name of the library, and the location of the entry is where the library is located. Also, the entry type will be set to Library.
CCREntry* newExtensionLibrary = new CCREntry();newExtensionLibrary->setRootElement("NewMDCName");newExtensionLibrary->setSubElement("ExtensionLibraries");newExtensionLibrary->setResourceName("mylibrary.dll");newExtensionLibrary->setResourceType("Library");theCCRInterface->addEntry(newExtensionLibrary);Step 4
You must specify the MDC that will be changed as well as the complete path of the file in which you want to track the logs.
theCCRInterface->setLoggingLocation("TheMDC", "d:\mymdc\logs\mymdc.log");Step 5
You must add the MDC name, the category name, and the priority level. Priority levels can be DEBUG, INFO, WARN, ERROR, or FATAL.
theCCRInterface->addLoggingCategory("TheMDC", "NewLoggingCategory", "DEBUG");
Using the CCRAccess Client
CCRAccess is a command-line client that allows easy initialization and manipulation of the CCR. This is an executable and should be the primary way to enter information into CCR. To use CCRAccess, enter the following on the command line:
CCRAccess [-options] [-commands]
Where:
[-options] is one or more of the options or wildcards shown in Table 13-1.
[-commands] is one of the commands shown in Table 13-2.
Note that this client is also available as a DLL (see "Using the CCRAccess DLL" section).
Scripting CCRAccess
CCRAccess can load and run scripts, allowing you to perform "bulk" manipulation of the CCR. Scripts are simple, separated lines, with each line a CCRAccess command or option.
For example:
-addMDC NewMDCName d:\mymdclocation;-addResource NewMDCName ExtensionLibraries Library EMPTYSTRING d:\mymdclocation\libs mylibrary.dll;-addLogLocation TheMDC d:\mymdc\logs\mymdc.log;-addLog TheMDC NewLoggingCategory DEBUGThis information can be stored in a file called mdcsetup.script. The following procedure is an example illustrating how you can use the CCRAccess command line interface and its scripting capabilities.
Step 1
CCRAccess -addMDC NewMDCName d:\mymdclocation;CCRAccess -addResource NewMDCName ExtensionLibraries Library EMPTYSTRING d:\mymdclocation\libs mylibrary.dll;CCRAccess -addLogLocation TheMDC d:\mymdc\logs\mymdc.log;CCRAccess -addLog TheMDC NewLoggingCategory DEBUGStep 2
CCRAccess -script mdcsetup.script
Using the CCRAccess DLL
CCR includes ccraccess.dll, a dynamic link library that provides all of the same functionality as the ccraccess.exe client described in the "Using the CCRAccess Client" section. The DLL version is significantly quicker to call (by approximately four seconds per call) than the EXE version. CCRAccess is often called during product installations, so developers who need to trim install times will find it useful to replace existing ccraccess.exe calls with ccraccess.dll calls.
The CCRAccess DLL interface is defined with the following prototype:
int EXPORTED ccraccess(char* commandLineInputString, char* resultFileName);
Where:
•
•
Calls to ccraccess.dll always return a zero on success and non-zero on failure.
Follow the steps below to call ccraccess.dll from a Windows-platform install (rul) file. Example 13-1 shows sample code that follows all of these steps.
Step 1
Step 2
Step 3
Step 4
Step 5
Step 6
Example 13-1 Using ccraccess.dll
function MODULENAME_postinstall(){#define CMD_CCR_CUSTOM_PREFIX_DLL "-addResource|Core|Custom|Custom"#define CMD_CCR_REG_HTTP_PORT_DLL CMD_CCR_CUSTOM_PREFIX_DLL+"|"+G_Port+"|"+"EMPTYSTRING|HttpPort"STRING resultFileName;//loading CCRDLL and reporting in case of errorif (loadCcrDll() != 0) thenszTit="CCRaccess Dll's Not Found";SetDialogTitle (DLG_MSG_INFORMATION,szTit);MessageBox("ccraccess Dll's are not found. Installation will abort",SEVERE);SureDeleteFile(WINDISK+"\\CMFLOCK.TXT");abort;endif;// Calling CCRDLL API to setnCcrVal=ccraccess.ccraccess(CMD_CCR_REG_HTTP_PORT_DLL, resultFileName);// More lines using the ccraccess.dll.UnloadCcrDll( );}
Using the CCR Java Interface
The Java interface for CCR is virtually identical to the functions and fields described in the "Using the CCR C++ API" section. However, it does rely heavily on the toString() functionality of CCRResponse and CCREntry. Java users should use com.cisco.core.ccr.CCRInterface when manipulating CCR.
com.cisco.core.ccr.CCREntry
This class is identical to the CCREntry C++ class, with obvious language differences. The changes are as follows:
•
•
•
Encryption is slightly different as the algorithms for this are on the C++ side. CCRInterface provides methods to handle this.
com.cisco.core.ccr.CCRInterface
This class is identical to the CCRInterface C++ class with obvious language differences.
The changes are as follows:
•
•
•
Access to the CCR via Java should be done through this class.
There are some additional methods to handle decryption of a CCREntry:
•
This method will decrypt the data value based on the entry's data password. You will need to know the size of the original data value.
•
This method will decrypt the name value based on the entry's name password. You will need to know the size of the original name value.
•
This method will decrypt the location value based on the entry's location password. You will need to know the size of the original location value.
•
This method will decrypt the key's value based on the entry's key password. You will need to know the size of the original key value.
com.cisco.core.ccr.CCRResponse
This class is identical to the CCRResponse C++ class, with obvious language differences. The changes are as follows:
•
•
•
JNICCRInterface
com.cisco.core.ccr.CCRInterface uses this class to bridge the Java/C++ gap via JNI. It is possible to use this class for the interface, but it is recommended that you use the CCRInterface class in com.cisco.core.ccr.
Encrypting and Decrypting CCREntry Values
You can encrypt and decrypt CCREntry name, data, location, and custom entry values. You must provide a key in the form of a file name or string value in order to encrypt or decrypt a value. The following topics show how to perform encryption and decryption using all of the available access methods:
Encrypting Entry Names
You can encrypt entry names via the C++, Java, or CCRAccess interfaces.
To encrypt an entry name using the C++ interface:
Step 1
Step 2
Step 3
The entry will be added to the CCR with its name value encrypted.
To encrypt an entry name using the Java interface:
Step 1
Step 2
Step 3
The entry will be added to the CCR with its name value encrypted.
To encrypt an entry name using CCRAccess:
Step 1
Step 2
CCRAccess -addResource MyMDC MyResourceSubdirectory MyResourceType MyResourceData MyResourceLocation /e:mykey MyResourceName <Any custom tag pairs>The entry will be added to the CCR with its name value encrypted.
Decrypting Entry Names
You can decrypt entry names via the C++, Java, or CCRAccess interfaces.
To decrypt an entry name using the C++ interface:
Step 1
Step 2
Step 3
The entry retrieved will have the decrypted name value if the password was correct.
To decrypt an entry name using the Java interface:
Step 1
Step 2
Step 3
The entry retrieved will have the decrypted name value if the password was correct.
To decrypt an entry name using CCRAccess:
Step 1
Step 2
CCRAccess -getResource MyMDC MyResourceSubdirectory MyResourceType MyResourceData MyResourceLocation /d:mykey "" <Any custom tag pairs>The entry retrieved will have the decrypted name value if the password was correct.
Encrypting Entry Data
You can encrypt entry data via the C++, Java, or CCRAccess interfaces.
To encrypt an entry's data using the C++ interface:
Step 1
Step 2
Step 3
The entry will be added to the CCR with its data value encrypted.
To encrypt an entry's data using the Java interface:
Step 1
Step 2
Step 3
The entry will be added to the CCR with its data value encrypted.
To encrypt an entry's data using CCRAccess:
Step 1
Step 2
CCRAccess -addResource MyMDC MyResourceSubdirectory MyResourceType /e:mykey MyResourceData MyResourceLocation MyResourceName <Any custom tag pairs>The entry will be added to the CCR with its data value encrypted.
Decrypting Entry Data
You can decrypt an entry's data via the C++, Java, or CCRAccess interfaces.
To decrypt an entry's data using the C++ interface:
Step 1
Step 2
The data value should be "".
Step 3
The entry retrieved will have the decrypted data value if the password was correct.
To decrypt an entry's data using the Java interface:
Step 1
Step 2
The data value should be "".
Step 3
The entry retrieved will have the decrypted data value if the password was correct.
To decrypt an entry's data using CCRAccess:
Step 1
Step 2
CCRAccess -getResource MyMDC MyResourceSubdirectory MyResourceType /d:mykey "" MyResourceLocation MyResourceName <Any custom tag pairs>The entry retrieved will have the decrypted data value if the password was correct.
Encrypting Entry Locations
You can encrypt an entry's location data via the C++, Java, or CCRAccess interfaces.
To encrypt an entry's location data using the C++ interface:
Step 1
Step 2
Step 3
The entry will be added to the CCR with its location value encrypted.
To encrypt an entry's location data using the Java interface:
Step 1
Step 2
Step 3
The entry will be added to the CCR with its location value encrypted.
To encrypt an entry's location data using CCRAccess:
Step 1
Step 2
CCRAccess -addResource MyMDC MyResourceSubdirectory MyResourceType MyResourceData /e:mykey MyResourceLocation MyResourceName <Any custom tag pairs>The entry will be added to the CCR with its location value encrypted.
Decrypting Entry Locations
You can decrypt an entry's location data via the C++, Java, or CCRAccess interfaces.
To decrypt an entry's location data using the C++ interface:
Step 1
Step 2
The location value should be "".
Step 3
The entry retrieved will have the decrypted location value if the password was correct.
To decrypt an entry's location data using the Java interface:
Step 1
Step 2
The location value should be "".
Step 3
The entry retrieved will have the decrypted location value if the password was correct.
To decrypt an entry's location data using CCRAccess:
Step 1
Step 2
CCRAccess -getResource MyMDC MyResourceSubdirectory MyResourceType MyResourceData /d:mykey "" MyResourceName <Any custom tag pairs>The entry retrieved will have the decrypted location value if the password was correct.
Encrypting Custom Entries
You can encrypt custom entry data via the C++, Java, or CCRAccess interfaces.
To encrypt custom entry data using the C++ interface:
Step 1
Step 2
Step 3
The entry will be added to the CCR with the custom tag value encrypted.
To encrypt custom entry data using the Java interface:
Step 1
Step 2
Step 3
The entry will be added to the CCR with the custom tag value encrypted.
To encrypt custom entry data using CCRAccess:
Step 1
Step 2
CCRAccess -addResource MyMDC MyResourceSubdirectory MyResourceType MyResourceData MyResourceLocation MyResourceName /e:mykey MyCustomKey MyCustomKeyValueThe entry will be added to the CCR with its custom tag value encrypted.
Decrypting Custom Entries
You can decrypt custom entry data via the C++, Java, or CCRAccess interfaces.
To decrypt custom entry data using the C++ interface:
Step 1
Step 2
The custom tag's value should be "".
Step 3
The entry will be retrieved from the CCR with the custom tag value decrypted.
To decrypt custom entry data using the Java interface:
Step 1
Step 2
The custom tag's value should be "".
Step 3
The entry will be retrieved from the CCR with the custom tag value decrypted.
To decrypt custom entry data using CCRAccess:
Step 1
Step 2
CCRAccess -getResource MyMDC MyResourceSubdirectory MyResourceType MyResourceData MyResourceLocation MyResourceName /d:mykey MyCustomKey""The entry retrieved will have the decrypted key value if the password was correct.
