ms_quant_configfile Class Reference [Mascot configuration files module]

Use this class in order to read/write quantitation.xml. More...

#include <ms_quant_configfile.hpp>

Inheritance diagram for ms_quant_configfile:

Collaboration diagram for ms_quant_configfile:

List of all members.

Public Member Functions
	ms_quant_configfile ()
	Default constructor.
	ms_quant_configfile (const ms_quant_configfile &src)
	Copying constructor.
	ms_quant_configfile (const char *fileName, const char *schemaFileName, const ms_connection_settings *cs=0)
	Cconstructor that reads the given file on construction.
	~ms_quant_configfile ()
	Destructor.
void	appendErrors (const ms_errors &src)
	Copies all errors from another instance and appends them at the end of own list.
void	appendMethod (const ms_quant_method *item)
	Adds a new quantitation method at the end of the list.
void	clearAllErrors ()
	Remove all errors from the current list of errors.
void	clearMethods ()
	Deletes all quantitation methods from the list.
void	copyFrom (const ms_errors *right)
	Use this member to make a copy of another instance.
void	copyFrom (const ms_quant_configfile *right)
	Copies all content from another instance.
void	defaultValues ()
	Call this member if you want to start again.
bool	deleteMethodByName (const char *name)
	Remove a quantitation method from the list in memory.
bool	deleteMethodByNumber (const int idx)
	Remove a quantitation method from the list in memory.
ms_connection_settings	getConnectionSettings () const
	Returns the sessionID and proxy server for use with an HTTP transfer.
const ms_errs *	getErrorHandler () const
	Retrive the error object using this function to get access to all errors and error parameters.
std::string	getFileName () const
	Returns a file name that is used to read configuration information.
int	getLastError () const
	Return the error description of the last error that occurred.
std::string	getLastErrorString () const
	Return the error description of the last error that occurred.
std::string	getMajorVersion () const
	Returns major document schema version as read from the file, otherwise the latest.
const ms_quant_method *	getMethodByName (const char *name) const
	Returns a quantitation method object by its name or a null value in case it is not found.
const ms_quant_method *	getMethodByNumber (const int idx) const
	Returns a quantitation method object by its number.
std::string	getMinorVersion () const
	Returns minor document schema version as read from the file, otherwise the latest.
int	getNumberOfMethods () const
	Returns a number of quantitation methods currently held in memory.
std::string	getSchemaDirectory () const
	Returns the schema directory name.
std::string	getSchemaFileName () const
	Returns the current schema file name that is used to validate XML file.
bool	isValid () const
	Call this function to determine if there have been any errors.
ms_quant_configfile &	operator= (const ms_quant_configfile &right)
	C++ style assignment operator.
void	read_buffer (const char *buffer)
	Reads configuration information from a buffer.
void	read_file ()
	Reads configuration information from the file.
std::string	save_buffer ()
	Creates a string representation of the XML document with all the content of the object.
void	save_file ()
	Stores modification information in the file.
void	setConnectionSettings (const ms_connection_settings &cs)
	Sets the sessionID and proxy server for use with an HTTP transfer.
void	setFileName (const char *name)
	Call this member to set a custom file name to read from a different location.
void	setSchemaDirectory (const char *dir)
	Sets common location for all versions of schema files.
void	setSchemaFileName (const char *name)
	Call this member to specify a custom schema file name for validating XML file.
bool	updateMethodByName (const char *name, const ms_quant_method *mod)
	Update the information for a specific quantitation method.
bool	updateMethodByNumber (const int idx, const ms_quant_method *mod)
	Update the information for a specific quantitation method.
std::string	validateDocument () const
	Validates the whole document against the schema and return errors as a string.

---

Detailed Description

Use this class in order to read/write quantitation.xml.

This file defines all necessary configuration information for performing quantitation experiments with Mascot.

After reading a file and before using the object check validity by calling isValid() and retrieve error descriptions with getLastErrorString() if not valid. Similarly, after writing out the file, isValid() can be used to check if the file has been created correctly and is valid for further use.

Examples:

config_quantitation.cpp.

---

Constructor & Destructor Documentation

ms_quant_configfile

(

)

Default constructor.

The default constructor just sets the current filename and schema name to be the defaults. Use this function to create an empty object before calling ms_mascotresfile::getQuantitation().

ms_quant_configfile

(

const ms_quant_configfile &

src )

Copying constructor.

Parameters:

src	another instance of this class to copy the content from.

ms_quant_configfile	(	const char *	fileName,
		const char *	schemaFileName,
		const ms_connection_settings *	cs = 0
	)

Cconstructor that reads the given file on construction.

An instance of this class is normally be created using this form of the constructor.

Parameters:

fileName	string that represents either local file name (for example, "C:/quantitation.xml") or a fully formed URL such as http://www.matrixscience.com/cgi . The filename may use backslashes or forward slashes on Windows and spaces in file or directory names are allowed.
schemaFileName	is a "schema location" string. See setSchemaFileName() for information on this parameter. To accept default schema location leave this parameter empty.
cs	a connection settings object for downloading the file from a Mascot server. This should contain a sessionID and optionally the proxy server settings. When reading a local file cs is not required and will be ignored.

---

Member Function Documentation

void appendErrors

(

const ms_errors &

src )

[inherited]

Copies all errors from another instance and appends them at the end of own list.

Parameters:

src	The object to copy the errors across from. See Maintaining object references: two rules of thumb.

void appendMethod

(

const ms_quant_method *

item )

Adds a new quantitation method at the end of the list.

Creates a new quantitation method object, copies all content from the object supplied as a parameter and adds it at the end of the methods list.

Parameters:

item	an instance of method object to copy content from.

Examples:

config_quantitation.cpp.

void clearAllErrors

(

)

[inherited]

Remove all errors from the current list of errors.

The list of 'errors' can include fatal errors, warning messages, information messages and different levels of debugging messages.

All messages are accumulated into a list in this object, until clearAllErrors() is called.

See Error Handling.

See also:

isValid(), getLastError(), getLastErrorString(), getErrorHandler()

Examples:

common_error.cpp, resfile_error.cpp, and resfile_summary.cpp.

void copyFrom

(

const ms_quant_configfile *

right )

Copies all content from another instance.

Parameters:

right

another instance of this class to copy the content from.

void copyFrom

(

const ms_errors *

right )

[inherited]

Use this member to make a copy of another instance.

Parameters:

right

is the source to initialise from

void defaultValues

(

)

Call this member if you want to start again.

All internal values are reset to their defaults, as if the object had been freshly created with the default constructor. However, the file name, schema location or connection settings are not reset. You need three additional calls:

    quant_configfile.setFileName("");
    quant_configfile.setSchemaFileName("");
    quant_configfile.setConnectionSettings(ms_connection_settings());

bool deleteMethodByName

(

const char *

name )

Remove a quantitation method from the list in memory.

Parameters:

name	name of the quantitation method for deletion.

Returns:

TRUE if the quantitation method has been found and successfully deleted and FALSE otherwise.

bool deleteMethodByNumber

(

const int

idx )

Remove a quantitation method from the list in memory.

Parameters:

idx	number of the method for deletion from 0 to (getNumberOfMethods() - 1).

Returns:

TRUE if the quantitation method has been found and successfully deleted and FALSE otherwise.

ms_connection_settings getConnectionSettings

(

)

const

Returns the sessionID and proxy server for use with an HTTP transfer.

See also the constructor documentation and setConnectionSettings().

Returns:

The current connection settings.

const ms_errs * getErrorHandler

(

)

const [inherited]

Retrive the error object using this function to get access to all errors and error parameters.

See Error Handling.

Returns:

Constant pointer to the error handler

See also:

isValid(), getLastError(), getLastErrorString(), clearAllErrors(), getErrorHandler()

Examples:

common_error.cpp, and http_helper_getstring.cpp.

std::string getFileName

(

)

const

Returns a file name that is used to read configuration information.

Returns:

currently set file location, which may not be the location from which the current content has been read if setFileName() has been called after reading the file.

int getLastError

(

)

const [inherited]

Return the error description of the last error that occurred.

All errors are accumulated into a list in this object, until clearAllErrors() is called. This function returns the last error that occurred.

See Error Handling.

See also:

isValid(), getLastErrorString(), clearAllErrors(), getErrorHandler()

Returns:

the error number of the last error, or 0 if there have been no errors.

Reimplemented in ms_mascotresfile.

std::string getLastErrorString

(

)

const [inherited]

Return the error description of the last error that occurred.

All errors are accumulated into a list in this object, until clearAllErrors() is called. This function returns the last error that occurred.

Returns:

Most recent error, warning, information or debug message

See Error Handling.

See also:

isValid(), getLastError(), clearAllErrors(), getErrorHandler()

Reimplemented in ms_mascotresfile.

Examples:

common_error.cpp, config_enzymes.cpp, config_fragrules.cpp, config_license.cpp, config_mascotdat.cpp, config_masses.cpp, config_modfile.cpp, config_procs.cpp, config_quantitation.cpp, config_taxonomy.cpp, http_helper_getstring.cpp, and tools_aahelper.cpp.

const ms_quant_method * getMethodByName

(

const char *

name )

const

Returns a quantitation method object by its name or a null value in case it is not found.

Parameters:

name	a unique name of the quantitation method.

Returns:

a read-only pointer to a method object. See Maintaining object references: two rules of thumb.

const ms_quant_method * getMethodByNumber

(

const int

idx )

const

Returns a quantitation method object by its number.

Parameters:

idx	number of the method from 0 to (getNumberOfMethods() - 1).

Returns:

a read-only pointer to a method-object. See Maintaining object references: two rules of thumb.

Examples:

config_quantitation.cpp.

int getNumberOfMethods

(

)

const

Returns a number of quantitation methods currently held in memory.

Returns:

total number of method elements in the configuration file.

Examples:

config_quantitation.cpp.

std::string getSchemaDirectory

(

)

const

Returns the schema directory name.

Returns:

current schema directory value.

std::string getSchemaFileName

(

)

const

Returns the current schema file name that is used to validate XML file.

Returns:

currently set schema file location.

bool isValid

(

)

const [inherited]

Call this function to determine if there have been any errors.

This will return true unless there have been any fatal errors.

See Error Handling.

Returns:

True if no fatal error occured

See also:

getLastError(), getLastErrorString(), clearAllErrors(), getErrorHandler()

Examples:

common_error.cpp, config_enzymes.cpp, config_fragrules.cpp, config_license.cpp, config_mascotdat.cpp, config_masses.cpp, config_modfile.cpp, config_procs.cpp, config_quantitation.cpp, config_taxonomy.cpp, http_helper_getstring.cpp, peptide_list.cpp, resfile_summary.cpp, and tools_aahelper.cpp.

ms_quant_configfile & operator=

(

const ms_quant_configfile &

right )

C++ style assignment operator.

Parameters:

right

another instance of this class to copy the content from.

Returns:

reference to the current object

void read_buffer

(

const char *

buffer )

Reads configuration information from a buffer.

This method is used when reading configuration information from a Mascot result file. Any old content in the object will be removed and substituted with the information read from the buffer.

Parameters:

buffer

string buffer that contains a valid quantitation XML document. Schema validation of the document is not performed.

void read_file

(

)

Reads configuration information from the file.

Reads the file from the local disk, or downloads the file from a Mascot web site. Check for errors using isValid() before using any other methods for retrieving content.

std::string save_buffer

(

)

Creates a string representation of the XML document with all the content of the object.

Creates a valid XML document and returns it as a string which can be used when writing out configuration information to a Mascot result file.

Returns:

XML document with the object content.

void save_file

(

)

Stores modification information in the file.

Check for errors after calling this method using isValid() to see if the operation has been successful or to get any schema validation errors. If the document is not valid it will still be saved.

Examples:

config_quantitation.cpp.

void setConnectionSettings

(

const ms_connection_settings &

cs )

Sets the sessionID and proxy server for use with an HTTP transfer.

This value would normally be passed in the constructor.

Parameters:

cs	is the new connection settings.

void setFileName

(

const char *

name )

Call this member to set a custom file name to read from a different location.

Calling this method does not cause an write to or read from disk. Use either read_file() or save_file() methods to read or write with the new file name.

Parameters:

name	a new file location (if empty a default file name will be assigned).

Examples:

config_quantitation.cpp.

void setSchemaDirectory

(

const char *

dir )

Sets common location for all versions of schema files.

This method allows setting a universal location for all schema versions. Client applications needn't be modified each time a new major version is introduced. However, it requires that all schemas (current and future) be placed in the same folder.

Calling this method will clear the list of pairs (alias/path) that could have possibly be submitted using setSchemaFileName().

Parameters:

dir	directory path for schema files.

void setSchemaFileName

(

const char *

name )

Call this member to specify a custom schema file name for validating XML file.

You should either supply the schema location explicitly for each version of schema or set the schema directory with setSchemaDirectory(). These two choices are mutualy exclusive and setting one of them will make another value empty.

Use this method to supply schema location as a list of pairs (alias/path) if all schemas you are using are potentially located in different folders. Essentially, it would require explicit path for each schema version and the list of pairs will have to be updated for each new major schema version.

An alternative would be to supply one common folder to retrieve any schemas that might potentially be introduced in future.

Deprecated usage: Old clients can supply a relative or an absolute file path (for example, "C:/quantitation_1.xsd") for schema version 1.

Newer clients have to submit a list of pairs "_schema_alias_ SPACE _file_path_", where SPACE is the space character. Currently supported aliases are "http://www.matrixscience.com/xmlns/schema/quantitation_1" and "http://www.matrixscience.com/xmlns/schema/quantitation_2".

Parameters:

name

schema location string. It can be left empty to accept the default location; otherwise it specifies the disk file locations for schema files. In this case, all file paths have to be URL-escaped ("C:/My%20Documents/quantitation_1.xsd"). The default location for schema files is the appropriate folder in Mascot installation or in Mascot Parser installation. Calling this method with an empty string will reset the schema location to standard default paths. Examples of valid values: "http://www.matrixscience.com/xmlns/schema/quantitation_2 ../schema%20files/quantitation_2.xsd" -- schema for version 1 will be taken from default location (if needed). "http://www.matrixscience.com/xmlns/schema/quantitation_1 C:/myfiles/quant_schema_1.xsd http://www.matrixscience.com/xmlns/schema/quantitation_2 ../schema%20files/quantitation_2.xsd"

bool updateMethodByName	(	const char *	name,
		const ms_quant_method *	mod
	)

Update the information for a specific quantitation method.

Parameters:

name	name of the quantitation method for updating.
mod	an object to copy the content from.

Returns:

TRUE if the quantitation method has been found and successfully updated and FALSE otherwise.

bool updateMethodByNumber	(	const int	idx,
		const ms_quant_method *	mod
	)

Update the information for a specific quantitation method.

Parameters:

idx	number of the method for updating from 0 to (getNumberOfMethods() - 1).
mod	an object to copy the content from.

Returns:

TRUE if the quantitation method has been found and successfully updated and FALSE otherwise.

std::string validateDocument

(

)

const

Validates the whole document against the schema and return errors as a string.

This method doesn't store the document and doesn't make the object invalid. Also, no errors are stored within the object. Therefore, this method can be called as many times as necessary without any consequences.

All validation errors will be returned back as a string. The XML parser will describe errors in terms of row and column numbers as if the document were actually saved in a file.

Returns:

validation errors as a string or an empty string if no errors are detected.

Examples:

config_quantitation.cpp.

---

The documentation for this class was generated from the following files:

• ms_quant_configfile.hpp
• ms_quant_configfile.cpp