org.omg.DsLogAdmin
Interface LogOperations

All Known Subinterfaces:

BasicLog, BasicLogOperations, EventLog, EventLogOperations, Log, NotifyLog, NotifyLogOperations, TypedEventLog, TypedEventLogOperations, TypedNotifyLog, TypedNotifyLogOperations

public interface LogOperations

The Log interface allows log clients to manipulate log records in the following manner:

• write records to the log
• query records from the log
• retrieve records from the log
• delete records from the log
• query/modify log record attributes

Method Summary

Log	copy_with_id(int id) creates an empty log with its attributes initialized to the same values as the log on which the operation was invoked.
Log	copy(IntHolder id) creates an empty log with its attributes initialized to the same values as the log on which the operation was invoked.
int	delete_records_by_id(long[] ids) Deletes specific log records from the log.
int	delete_records(java.lang.String grammar, java.lang.String c) Deletes log records that match the given constraint from the log.
void	flush() The flush() operation guarantees that all events sent to the log prior to the invocation of the flush() operation will be written to final storage medium before the flush() operation completes.
AdministrativeState	get_administrative_state() Returns the administrative state of the log.
AvailabilityStatus	get_availability_status() Returns a struct that reflects the availability status of the Log.
short[]	get_capacity_alarm_thresholds() Returns a sequence of value that specifies, as a percentage of max log size, the points at which a ThresholdAlarm event will be generated.
long	get_current_size() Returns the current size of the log measured in bytes.
ForwardingState	get_forwarding_state() Returns the forwarding state of a log.
TimeInterval	get_interval() Returns the coarse grained time interval during which an unlocked and enabled Log is functional.
short	get_log_full_action() Returns the action that will be taken when the maximum size of the log has been reached.
short[]	get_log_qos() Returns a list of the quality of service properties supported by the log.
int	get_max_record_life() Returns the maximum number of seconds a record is stored in a log.
long	get_max_size() Returns the size of the log measured in number of bytes.
long	get_n_records() Returns the current number of records contained in the log.
OperationalState	get_operational_state() Returns the operational capability of the log to perform its function.
NVPair[]	get_record_attribute(long id) Returns the attributes of a given log record indicated by the id parameter.
WeekMaskItem[]	get_week_mask() Returns the fine grained time intervals during which an unlocked and enabled Log is functional.
int	id() The id() operation returns the id of a log.
int	match(java.lang.String grammar, java.lang.String c) Searches the log for all log records that match the given constraint and returns number of records matching constraint.
LogMgr	my_factory() The my_factory() operation returns the log factory object that created the log.
LogRecord[]	query(java.lang.String grammar, java.lang.String c, org.omg.DsLogAdmin.IteratorHolder i) Searches the log for all log records that match the given constraint.
LogRecord[]	retrieve(long from_time, int how_many, org.omg.DsLogAdmin.IteratorHolder i) Reads the log records in the log sequentially starting from any given time.
void	set_administrative_state(AdministrativeState state) Sets the administrative state of the log.
void	set_capacity_alarm_thresholds(short[] threshs) Sets the points at which a ThresholdAlarm event will be generated.
void	set_forwarding_state(ForwardingState state) Sets the forwarding state of a log.
void	set_interval(TimeInterval interval) Sets the start and stop time during which an unlocked and enabled log is functional.
void	set_log_full_action(short action) Sets which action should be taken when the maximum size of the log has been reached.
void	set_log_qos(short[] qos) Sets the quality of service properties of the log.
void	set_max_record_life(int life) Sets the maximum number of seconds a record is stored in a log.
void	set_max_size(long size) Sets the maximum log size.
void	set_record_attribute(long id, NVPair[] attr_list) sets the log record indicated by the id parameter to the attributes specified by the attr_list parameter.
int	set_records_attribute(java.lang.String grammar, java.lang.String c, NVPair[] attr_list) Set all records that matches the constraints with same attr_list
void	set_week_mask(WeekMaskItem[] masks) Sets the fine grained time intervals during which an unlocked and enabled log is functional.
void	write_recordlist(LogRecord[] list) Write to the log.
void	write_records(Any[] records) Write to the log.

Method Detail

flush

void flush()
           throws UnsupportedQoS

The flush() operation guarantees that all events sent to the log prior to the invocation of the flush() operation will be written to final storage medium before the flush() operation completes.

Throws:

UnsupportedQoS - if a log implementation does not support QoSFlush property.

copy_with_id

Log copy_with_id(int id)
                 throws LogIdAlreadyExists

creates an empty log with its attributes initialized to the same values as the log on which the operation was invoked. The log factory will be notified of the existence of this new log.

Parameters:

id - The log id of the created log is specified as an in parameter.

Throws:

LogIdAlreadyExists - if the log id already exists within the scope of the log factory.

copy

Log copy(IntHolder id)

creates an empty log with its attributes initialized to the same values as the log on which the operation was invoked. The log factory will be notified of the existence of this new log.

Parameters:

id - The log id of the created log is generated and returned as an out parameter.

Returns:

the created log object reference.

get_record_attribute

NVPair[] get_record_attribute(long id)
                              throws InvalidRecordId

Returns the attributes of a given log record indicated by the id parameter.

Parameters:

id - The ID of the log record want to retrieve.

Returns:

list of attributes.

Throws:

InvalidRecordId - If the log record does not exist.

set_records_attribute

int set_records_attribute(java.lang.String grammar,
                          java.lang.String c,
                          NVPair[] attr_list)
                          throws InvalidGrammar,
                                 InvalidConstraint,
                                 InvalidAttribute

Set all records that matches the constraints with same attr_list

Parameters:

grammar - indicates how to interpret the constraint string. The default grammar is "EXTENDED_TCL" specified in the Notification Service.

constraint - Specify which log records the client wishes to set attributes.

attr_list - The attributes.

Returns:

the number of records whose attributes are set is returned if successful.

Throws:

InvalidGrammar - if the implementation does not support the grammar specified.

InvalidConstraint - if the constraint string is invalid.

InvalidAttribute - if one of the attributes is invalid.

set_record_attribute

void set_record_attribute(long id,
                          NVPair[] attr_list)
                          throws InvalidRecordId,
                                 InvalidAttribute

sets the log record indicated by the id parameter to the attributes specified by the attr_list parameter.

Parameters:

id - The ID of the log record want to set attribute.

attr_list - The attributes.

Throws:

InvalidRecordId - If the log record does not exist.

InvalidAttribute - if one of the attributes is not valid.

write_recordlist

void write_recordlist(LogRecord[] list)
                      throws LogFull,
                             LogOffDuty,
                             LogLocked,
                             LogDisabled

Write to the log. The log record is written directly to the log and is not subject to the log filter and also will not be forwarded. This operation allows the output of a query of one log to be written to another log. In this case, only the "info" field (event content) of the RecordData struct is written to the log, the LogRecord id and logging time will be assigned by the log.

Parameters:

list - The record list returned by a query.

Throws:

LogFull - If the log?s availability status is "log_full" and its LogFullAction is "halt," then a LogFull exception is raised and the number of log records written will be returned in the exception.

LogOffDuty - If the log?s availability status is "off_duty", then a LogOffDuty exception is raised and no log records are written.

LogLocked - If the log?s administrative state is "locked", then a LogLocked exception is raised and no log records are written.

LogDisabled - If the log?s operational state is "disabled", then a LogDisabled exception is raised and no log records are written.

write_records

void write_records(Any[] records)
                   throws LogFull,
                          LogOffDuty,
                          LogLocked,
                          LogDisabled

Write to the log. The log record is written directly to the log and is not subject to the log filter and also will not be forwarded.

Parameters:

records - A sequence of Anys as a parameter, each Any contains the event to be logged.

Throws:

LogFull - If the log?s availability status is "log_full" and its LogFullAction is "halt," then a LogFull exception is raised and the number of log records written will be returned in the exception.

LogOffDuty - If the log?s availability status is "off_duty", then a LogOffDuty exception is raised and no log records are written.

LogLocked - If the log?s administrative state is "locked", then a LogLocked exception is raised and no log records are written.

LogDisabled - If the log?s operational state is "disabled", then a LogDisabled exception is raised and no log records are written.

delete_records_by_id

int delete_records_by_id(long[] ids)

Deletes specific log records from the log.

Parameters:

ids - A sequence of log record ids as a parameter.

Returns:

the number of records deleted. If an empty sequence of records is specified, then no records are deleted and the operation returns a value of 0.

delete_records

int delete_records(java.lang.String grammar,
                   java.lang.String c)
                   throws InvalidGrammar,
                          InvalidConstraint

Deletes log records that match the given constraint from the log. Queries can be constructed to retrieve log records based on log time, log record id, attributes, and event contents.

Parameters:

grammar - The grammar parameter indicates how to interpret the constraint string. The default grammar is "EXTENDED_TCL" specified in the Notification Service.

c - The constraint parameter specifies which log records the client wishes to receive.

Returns:

the number of log records that match the constraint is returned. The log records themselves are not returned.

Throws:

InvalidGrammar - if the implementation does not support the grammar specified.

InvalidConstraint - if the constraint string is invalid.

match

int match(java.lang.String grammar,
          java.lang.String c)
          throws InvalidGrammar,
                 InvalidConstraint

Searches the log for all log records that match the given constraint and returns number of records matching constraint. Queries can be constructed to retrieve log records based on log time, log record id, attributes, and event contents.

Parameters:

grammar - The grammar parameter indicates how to interpret the constraint string. The default grammar is "EXTENDED_TCL" specified in the Notification Service.

c - The constraint parameter specifies which log records the client wishes to receive.

Returns:

the number of log records that match the constraint is returned. The log records themselves are not returned.

Throws:

InvalidGrammar - if the implementation does not support the grammar specified.

InvalidConstraint - if the constraint string is invalid.

retrieve

LogRecord[] retrieve(long from_time,
                     int how_many,
                     org.omg.DsLogAdmin.IteratorHolder i)

Reads the log records in the log sequentially starting from any given time.

Parameters:

from_time - Indicates which time to start from.

how_many - Indicates how many log records to retrieve, and the sign of the how_many parameter indicates the direction (positive for forward retrieval or negative for backward retrieval).

i - The log records are returned as a sequence and an iterator may be provided as an out parameter to deal with large retrievals. If the iterator is not needed, then the iterator will hold a nil object reference

query

LogRecord[] query(java.lang.String grammar,
                  java.lang.String c,
                  org.omg.DsLogAdmin.IteratorHolder i)
                  throws InvalidGrammar,
                         InvalidConstraint

Searches the log for all log records that match the given constraint. Queries can be constructed to retrieve log records based on log time, log record id, attributes, and event contents.

Parameters:

grammar - The grammar parameter indicates how to interpret the constraint string. The default grammar is "EXTENDED_TCL" specified in the Notification Service.

c - The constraint parameter specifies which log records the client wishes to receive.

i - The log records are returned as a sequence and an iterator may be provided as an out parameter to deal with large query results. If the iterator is not needed, then the iterator will hold a nil object reference.

Throws:

InvalidGrammar - if the implementation does not support the grammar specified.

InvalidConstraint - if the constraint string is invalid.

set_week_mask

void set_week_mask(WeekMaskItem[] masks)
                   throws InvalidTime,
                          InvalidTimeInterval,
                          InvalidMask

Sets the fine grained time intervals during which an unlocked and enabled log is functional. These fine grained time intervals are only valid within the coarse grained time interval specified by the log duration operations. The weekly scheduling only applies during log duration time (start/stop time). A log performs its logging function when the logging time falls within the log duration and one or more of the log scheduling times is indicated in the weekly mask. The weekly schedule does not effect the status to event forwarding. By default, the weekly mask is empty when a log is created. An empty weekly mask means that logging should take place during the whole week. An AttributeValueChange event is generated whenever the week mask of a log is set.

Parameters:

masks - The fine grained time intervals during which an unlocked and enabled log is functional.

Throws:

InvalidTime - if the time specified in the time interval is invalid.

InvalidTimeInterval - if the time interval specified is invalid.

InvalidMask

get_week_mask

WeekMaskItem[] get_week_mask()

Returns the fine grained time intervals during which an unlocked and enabled Log is functional.

set_capacity_alarm_thresholds

void set_capacity_alarm_thresholds(short[] threshs)
                                   throws InvalidThreshold

Sets the points at which a ThresholdAlarm event will be generated. An AttributeValueChange event is generated whenever the capacity alarm threshold of a log is set.

Parameters:

threshs - The threshold list.

Throws:

InvalidThreshold - if the threshold list contains invalid values.

get_capacity_alarm_thresholds

short[] get_capacity_alarm_thresholds()

Returns a sequence of value that specifies, as a percentage of max log size, the points at which a ThresholdAlarm event will be generated. Log capacity alarm thresholds are used to warn clients when a log is approaching full. If the capacity of a log exceeds that of one of its log capacity alarm thresholds, then a ThresholdAlarm event is generated to indicate that the log is approaching full.

get_availability_status

AvailabilityStatus get_availability_status()

Returns a struct that reflects the availability status of the Log.

set_interval

void set_interval(TimeInterval interval)
                  throws InvalidTime,
                         InvalidTimeInterval

Sets the start and stop time during which an unlocked and enabled log is functional. An AttributeValueChange event is generated whenever the log duration interval of a log is set (either start or stop).

Parameters:

interval - The time interval.

Throws:

InvalidTime - if the time specified in the time interval is invalid.

InvalidTimeInterval - if the time interval specified is invalid.

get_interval

TimeInterval get_interval()

Returns the coarse grained time interval during which an unlocked and enabled Log is functional.

get_operational_state

OperationalState get_operational_state()

Returns the operational capability of the log to perform its function. A StateChange event is generated whenever the operational state of a log changes.

set_forwarding_state

void set_forwarding_state(ForwardingState state)

Sets the forwarding state of a log. It allows clients to control whether a log should forward records to any event consumers connected to the log. A StateChange event is generated whenever the forwarding state of a log is set.

Parameters:

state - The forwarding state.

get_forwarding_state

ForwardingState get_forwarding_state()

Returns the forwarding state of a log.

set_administrative_state

void set_administrative_state(AdministrativeState state)

Sets the administrative state of the log. By default, the administrative state is set to "unlocked" when a log object is created. A StateChange event is generated whenever the administrative state of a log changes.

Parameters:

state - The administrative state.

get_administrative_state

AdministrativeState get_administrative_state()

Returns the administrative state of the log.

set_log_full_action

void set_log_full_action(short action)
                         throws InvalidLogFullAction

Sets which action should be taken when the maximum size of the log has been reached. An AttributeValueChange event is generated whenever the log full action of a log is set.

Parameters:

action - The action to be taken.

Throws:

InvalidLogFullAction - if the input action is neither wrap nor halt.

get_log_full_action

short get_log_full_action()

Returns the action that will be taken when the maximum size of the log has been reached. Two options are currently defined:

• wrap: The oldest records in the log, based on the log time, will be deleted to free resources for the creation of new records.
• halt: No more records will be logged and all incoming events are discarded. Records already in the log will be retained.

get_n_records

long get_n_records()

Returns the current number of records contained in the log.

get_current_size

long get_current_size()

Returns the current size of the log measured in bytes.

set_max_size

void set_max_size(long size)
                  throws InvalidParam

Sets the maximum log size. If a value of zero is supplied, then the log size will be set to have no predefined limit. An AttributeValueChange event is generated whenever the size of a log is set.

Parameters:

size - The log size

Throws:

InvalidParam - if the maximum log size specified is less than the current log size.

get_max_size

long get_max_size()

Returns the size of the log measured in number of bytes. A log may have an indeterminate size.

set_max_record_life

void set_max_record_life(int life)

Sets the maximum number of seconds a record is stored in a log. An AttributeValueChange event is generated whenever the max record life of a log is set.

Parameters:

life - the maximum number of seconds a record is stored in a log

get_max_record_life

int get_max_record_life()

Returns the maximum number of seconds a record is stored in a log.

set_log_qos

void set_log_qos(short[] qos)
                 throws UnsupportedQoS

Sets the quality of service properties of the log.

Parameters:

qos - The list of the quality of service properties to set to the log

Throws:

UnsupportedQoS - if an implementation does not support the specified quality of service property.

get_log_qos

short[] get_log_qos()

Returns a list of the quality of service properties supported by the log.

id

int id()

The id() operation returns the id of a log. Log objects are created by a log factory and each log is assigned an id that uniquely identifies the log object within the factory.

Returns:

The log id of the log.

my_factory

LogMgr my_factory()

The my_factory() operation returns the log factory object that created the log. The return type LogMgr is the abstract interface of all log factories. A client should narrow LogMgr to the actual derived log factory interface. Clients need to narrow the LogMgr to a specific log factory interface if they wish to create new logs or receive log generated events.

Returns:

The reference of the log factory object that created the log.