This Schema defines the XML Interface for the OSS IP Billing API (JSR 130) of the OSS Through Java (tm) Initiative. This Schema was generated by the OSS Through Java XML Toolkit Doclet 1-26-2004 7:5 This interface models a UsageDataAvailableEvent, which is an event that will be sent by the <CODE>Producer</CODE> to the client for informing the availability of new data. This interface models a MediationCapabilityChangeEvent, which is an event that will be sent by the <CODE>Producer</CODE> to the clients to inform the introduction of new data <CODE>formats</CODE>. This interface models the PropertyDescriptor of the UsageDataAvailableEvent. This interface documents and specifies the filterable prooperties of a UsageDataAvailableEvent notification. An implementation must provide the makeEvent method to return an empty manufactured event instance to the invoker. This interface models the PropertyDescriptor of the MediationCapabilityChangeEvent. This interface documents and specifies the filterable properties of a MediationCapability notification. This interface supports the low-level detailing of a MediationCapabilityChangeEvent emitted by a Producer entity. This interface provides many helpful methods to clients interested in decoding such an event, received by them. This represents a base interface to define a Schema definition to describe a collection format or output format of a Usage Data Record. The Schema descriptions are set and returned as {@link java.lang.Object}. This allows the API to let a specific implementation to support the passing of a schema definition to a client. Details of the schema definition construction and details of schema definition deciphering are left up to the individual implementations and the API clients. This interface models the behavior for all types of Usage Record Filter interfaces in the IP Billing API. A Usage Record Filter instance supports setting of the various queryable attributes, by a which Usage Data Records can be filtered for retrieval. Some common querying parameters for a Usage Data Record supported by this interface are: <UL> <li> Usage Data Category: Usage Data Application type: VoD, IM, M-COMMERCE, Voice <li> Usage Data Format: IPDR, (X)-CDR, ... <li> Usage Data Format Version - String value of version (1.0, 2.5, etc.). <li> Usage Data Encoding - XML, XDR, ASCII, ASN.1/BER, CSV, OSS/J Usage Record. <li> Usage Data Timestamp - Records with this timestamp of collection time. <li> Usage Attribute field values - These can be added to this filter instance at any time by utilizing the base interface method {@link #setAttributeValue}. collection time. <li> Usage Data Collection Period - Records collected between these timestamps. </UL> It is also possible that new interfaces could be derived from this interface to represent specific filterable attributes for the querying the Usage Data Records in question. All the attributes set in this Fitler instances are cancatenated using logical AND expression for query filter purposes. This is the base interface for all types of OSS/J Usage Records. Any OSS/J Usage Record must implement this interface. The OSS/J Usage Record is NOT a Managed Entity type. There is no <CODE>primaryKey</CODE> for this <CODE>UsageRecValue</CODE>. A Usage Record value is just a data record. It can be decoded with the {@link javax.oss.cfi.activity.RecordDescriptor} type information. This Type Description is provided by a <CODE>UsageRecValueIterator</CODE> instance. This interface also provides standardized get and set methods to primitive type attributes (fields) and composite type attributes (by means of <CODE>Object</CODE> ). This helps in standardizing access to member attributes of a Usage Record. This interface represents a Query Value that allows clients to query a <CODE>Producer</CODE> for a subset of its collected Usage Records using one or more Usage Data Record attributes as part of the filter's attributes. The Query for Usage Records may consist of specifying multiple <CODE>UsageRecFilterValue</CODE> objects, which are used as templates for building the query expression. All the Filter Objects in the array are concatenated, using logical OR operation. Each individual <CODE>UsageRecFilterValue</CODE> object may consist of multiple filterable attribute specification. These attributes are concatenated together using a logical AND operation. This interface represents a Query Value that allows clients to query a <CODE>Producer</CODE> for a subset of its collected Usage Records using one or more Usage Data Record attributes as part of the filter's attributes. The Query for Usage Records uses a <CODE>UsageRecFilterValue</CODE> to specify the criteria for limiting the data. Also, a <CODE>ProducerKey/CODE> can be provided to specify whether the data query is associated with a specific Producer or whether all data should be considered in the query. This interface is a Query Value that allows a <CODE>Producer</CODE> Entity to be retrieved by its attributes or capabilities. A Query operation using such a query may result in zero, one or multiple <CODE>Producer</CODE> Entities to be returned. For Query expression purposes all attributes of <CODE>MeidationCapability</CODE> instnace are concatenated, using logical AND operation. This interface encapsulates the <CODE>PrimaryKey</CODE> of a <CODE>TransferStatus</CODE> entity. The <CODE>PrimaryKey</CODE> encapsulation allows a <CODE>TransferStatus</CODE> entity to be uniquely identified with just one or a combination of two or more attributes and their values. This insulates the API as well as the implementations from having to change each time a new attribute must be included to the definition of its <CODE>PrimaryKey</CODE>. This is the base interface for all <CODE>TransferStatus</CODE> primary key interfaces, with just the DN being defined as the key attribute for now. Any derived interfaces are free to add their own attributes. The primary key for a transfer session consists of a unique session id within the operating domain, plus <CODE>ProducerKey</CODE>, which are involved in the data transfer. This interface represents the attributes of all types of Data Transfer Status Entities in IP Billing API. This is a base Value Object interface to the <CODE>TransferStatusValue</CODE> Entity. This interface and its sub interfaces (if any) provide several ways to access the attributes: <UL> <LI>Attributes can be accessed through standard JavaBeans get/set (isSet) methods. <LI>Attributes can be accessed through the generic methods defined in <CODE>AttributeAccess</CODE> <UL> <LI><CODE>Object getAttributeValue(String attributeName)</CODE> <LI><CODE>void setAttributeValue(String attributeName, Object newValue)</CODE> </UL> </UL> A <CODE>TransferStatusValue</CODE> entity is used to persistently represent information regarding the transfer of Usage Records from a <CODE>Producer</CODE> to a client. This base interface only provides the ability to store retrieve the status of the data transfer and the Usage Record Subscription value object associated with this transfer. More specific interfaces can be developed by means of derivation to provide more useful behavior for a specific type of transfer. For example, if a <CODE>Producer</CODE> Entity capable of re-transmissions, a specialized <CODE>TransferStatusValue</CODE> Entity can save the information about failed Usage Record transfers, so that, they may be retried or re-conciled at a later time. An entity of <CODE>TransferStatusValue</CODE> is created by the <CODE>Producer</CODE>, whenever a transfer record needs to be kept. The reporting parameters are preserved in the optional <CODE>reportingParams</CODE> attribute for understanding the reporting schemes involved. The <CODE>TransferStatusValue</CODE> entity is not removed by the <CODE>Producer</CODE> entity after the Data Transfer is complete. Instead, it is left to persistently log the Data Transfer information, for auditing purposes. In order to avoid creation of large number of Data Transfer Status Entities in the <CODE>Producer</CODE>'s storage, there must be an aging policy for retiring the unused Usage Data Transfer Status entities. Currently this is left unspecified by this API. A <CODE>TransferStatusKey</CODE> is a unique identifier attribute, present for each <CODE>TransferStatus</CODE> entity represented by <CODE>TransferStatusValue</CODE> object. It is used to identify a single <CODE>TransferStatus</CODE> entity. A <CODE>TransferStatusKey</CODE> value object is returned to the client during setting up of Data Transfer Session between a client and <CODE>Producer</CODE>. The Type, ApplicationDN and ApplicationContext are included in super interface <CODE>ManagedEntityKey</CODE>, because a <CODE>primaryKey</CODE> is only unique within an application instance as given by the ApplicationDN running in a given naming system as given by the ApplicationContext::URL The <CODE>TransferStatusPrimaryKey</CODE> is the <CODE>primaryKey</CODE> representation of the <CODE>TransferStatusKey</CODE>. This interface is also the factory for creating the instances of <CODE>TransferStatusPrimaryKey</CODE>. This is base class for all IP Billing API Exceptions. This inherits from Exception, not RuntimeException. This exception is thrown for Billing API functionality specific problems. This new class is required because J2EE containers deal with RuntimeException in a special way, see EJB specification. This class represents exceptions related to Data Format errors. It could be thrown by IP Billing API to indiate problems such as encountering unsupported data format, non-conformant data formats, etc. This is base interface, representing the attribute values of any type of <CODE>Producer</CODE> Entity in the IP Billing API. The Producer in the IP Billing API is an <CODE>Activity</CODE> (see {@link javax.oss.cfi.activity.ActivityValue}), which knows how and what type of data to collect and how to report it to the client. This is a base Value Object interface to the <CODE>Producer</CODE> entity. This interface and its sub interfaces (if any) provide several ways to access the attributes: <UL> <LI>Attributes can be accessed through standard JavaBeans get/set (isSet) methods. <LI>Attributes can be accessed through the generic methods defined in <CODE>AttributeAccess</CODE> <UL> <LI><CODE> Object getAttributeValue(String attributeName)</CODE> <LI><CODE> void setAttributeValue(String attributeName, Object newValue)</CODE> </UL> </UL> Lists the known ProducerValue sub types in the Producer System. This method can be invoked by the clients of the API to know the various supported Producer Entity types of a given system. Lists the known ProducerKey sub types in the Producer System. This method can be invoked by the clients of the API to know the Key instances of various supported Producer Entity types of a given system. Lists the known UsageRecFilterTypes sub types in the Producer System. This method can be invoked by the clients of the API to know the various supported Usage Record Filter types of a given system. Lists the known MediationCapability sub types in the Producer System. This method can be invoked by the clients of the API to know the various supported mediation capability types of a given system. Create a new <CODE>Producer</CODE> Entity. On creation of the <CODE>Producer</CODE>, minimally necessary information must be supplied in order to identify the <CODE>Producer</CODE>. This includes the supplying the information on <CODE>Producer</CODE>'s key attributes, its name and DN. If a <CODE>ProducerKey</CODE> attribute is specified in the <CODE>ProducerValue</CODE> value object during the create operation, an IllegalArgumentException is raised. The name of a <CODE>Producer</CODE> must be unique within a given system deploying the IP Billing API. The capability descriptor of the created <CODE>Producer</CODE>'s entity, namely attribute that is the instance of <CODE>MediationCapability</CODE>, may be left empty (unset) at the creation time, implying that a <CODE>Producer</CODE> is not ready to be discovered. The <CODE>MediationCapability</CODE> attribute of the <CODE>Producer</CODE> may be set to different values during its lifetime. Each time, this value is changed, the Producer Entity emits a {@link javax.oss.ipb.event.MediationCapabilityChangeEvent} Notification to the common JVTEventTopic, which then will be received by the registered clients. However, a <CODE>Producer</CODE> that does not support setting this attribute, may throw an UnsupportedOperationException. Also, a <CODE>Producer</CODE> Entity may throw a IllegalArgumentException for a Set operation on this attribute, if it indicates a arising of a potential conflict with on-going operations. Similar rules apply to other Value objects, such as Usage Record Descriptors, that are associated with a <CODE>Producer</CODE> Entity. Create multiple <CODE>Producer</CODE> entities with the specified value templates. A Standard OSS/J bulk create entity operation, with best effort semantics. Remove a single <CODE>Producer</CODE> entity. A Standard OSS/J atomic remove operation to remove a single <CODE>Producer</CODE> Enitty. Remove multiple <CODE>Producers</CODE> by keys, using best effort. A Standard OSS/J bulk remove operation to remove multiple <CODE>Producer</CODE> Enitties, using best effort semantics. Remove multiple <CODE>Producers</CODE> by value template, using best effort. Get attributes of a single <CODE>Producer</CODE> entity Get attributes of multiple <CODE>Producer</CODE> entities by keys. Get attributes of multiple <CODE>Producer</CODE> entities by template Set attributes of a single managed object, by its key Set attributes of multiple managed objects by their keys - best effort. Set attributes of multiple managed objects by template - best effort. Query the <CODE>Producer</CODE> by its capability attributes. This method can use <CODE>QueryProducersByMediationCapability</CODE> named query. Returns the list of all Mediation (Conversion) possibilities supported by IP Billing System. This method is primarily invoked by the clients to find out the current system's mediation capabilities. Once the desired set of mediation capability values are located in the results, the client typically extracts these and uses them to create an instance of ProducerValue with additional attributes. The client may then locate an existing Producer by the created value template (see {@link #getProducersByTemplate}), or query the producer by the mediation capability values (see {@link javax.oss.ipb.query.QueryProducersByMediationCapability}). Alternatively, the client may also create a new Producer Entity by using any one of the createProducer... type methods. Returns a MediationCapability instance that is a subset of value array returned by {@link #getSupportedMediationCapabilities}, for the specified <CODE>desiredCapability</CODE> parameter. This is the negotiation method for the client to request Mediation capabilities from a Producer. The client builds a desired mediation capability value and then passes it along to the producer session to negotiate this capability from a specific producer. If the <CODE>producerKey</CODE> is omitted, then all the <CODE>Producer</CODE>s for this session will be considered. If not acceptable, the <CODE>Producer</CODE> will throw an IPBAPIException. Otherwise, it returns a new <CODE>MediationCapability</CODE> value that contains the commonly agreeable set of capabilities. This method indicates whether Usage Data Transfers can be monitored for the Producer in question, by creating the TransferStatusValue audit record by the implementation. If an implementation doesn't support audit trailing of the usage data transfers, it should return <CODE>false</CODE> value. Query the Usage Records by its filterable attribues. This is a one time query method which returns a bunch of matching usage reocrds as a iterator. However, no record of any querying is kept. After the iterator is removed, this query and its results are completely forgotten. This is a client initiated ad-hoc querying of usage data in a System. An implementation that supports this method, will be able to service real-time queries from the client for usage data for both current (snap-shot) as well historical data. This operations returns the Iterator to the UsageRecValue resutls. This operation can be invoked by the client at any time. If an implementation cannot support returning the Usage Data as an Iterator, it will throw a UnsupportedOperationException. The difference between this operation and {@link #queryUsageDataInformation} is that the latter returns an iterator to the multiple ReportInfo values. Each of the ReportInfo value can then be inspected by the client to discover the URL or stream connection information to the actual Usage Data on the System. Such approach can be used by the implementations that do not support Iterator based retrieval of Usage Record Data, but still want to allow the clients to query for the indirect Report Information. Query the on-going or completed or failed Transfers by queryable attribues. Get the Iterator to the Usage Data Records collected by the Producer This is called by the client after it receives a UsageDataAvailableEvent notification from the Producer. The client passes the same notfication value back to the Producer with additional parameters identifying date constraints for the results, to aid in possibly retrieving only newer information. This operation is used by the client to retrieve the results using OSS/J Iterator approach. If the Iterator Report Mode is not one of the Report Modes supported by this Session, an UnsupportedOperationException is thrown. Please see {@link #getSupportedReportModes}. If beginTime parameter is not null, all the reports created beginning from this date are returned by the iterator. If it is null, all the reports by this Activity are retrieved until the endDate is reached. If the endDate is specified, only Report Data collected until this endDate is returned. If it is null, all Report Data from the beginDate is returned. Get the Iterator to the Usage Data Record Results Information. This introduces an extra level of indirection over the method {@link #getUsageRecordsByIterator}. This can be called by the client after it receives a UsageDataAvailableEvent notification or at anytime to retrieve a list of ReportInfo about the Usage Records in a Producer. The client passes the Producer Key to the Producer Session with additional parameters identifying date constraints for the results, to aid in possibly retrieving only newer information. If beginTime parameter is not null, information for all the reports accumulated beginning from this date are returned by the iterator. If it is null, information for all the reports by this Activity accumulated until the endDate is reached are returned. If the endDate is specified, only Report Data collected until this endDate is returned. If it is null, all Report Data accumulated from the beginDate is returned. Get the Iterator to the Usage Data Results Information. This introduces an extra level of indirection over the method {@link #queryUsageRecords}. This operations returns the Iterator to the ReportInfo values. This operation can be invoked by the client at any time during its life-time. This operation returns an iterator to the multiple ReportInfo values. Each of the ReportInfo value can then be inspected by the client to discover the URL or stream information to the actual Usage Record Data on the System. Such approach can be used by the implementations that do not support Iterator based retrieval for direct Usage Record Data, but still want to allow the clients to query for the indirect Report Information about the Usage Data Records. This interface encapsulates the <CODE>PrimaryKey</CODE> of a <CODE>Producer</CODE> entity. The <CODE>PrimaryKey</CODE> encapsulation allows a <CODE>Producer</CODE> entity to be uniquely identified with just one or a combination of two or more attributes and their values. This insulates the API as well as the implementations from having to change each time a new attribute must be included to the definition of its <CODE>PrimaryKey</CODE>. This is the base interface for all <CODE>Producer</CODE> primary key interfaces, with just the DN being defined as the key attribute for now. Any derived interfaces are free to add their own attributes. This defines the base descriptor interface for expressing of Mediation Capabilitties of a <CODE>Producer</CODE> Entity. More specialized sub interfaces can be implemented to add more capabilities. Also, by following OSS/J Value object pattern, each capability attribute has JavaBeans like get and set methods for access by client of this interface. This interface is used by the <CODE>ProducerValue</CODE> and <CODE>JVTProducerSession</CODE> interfaces to return the mediation capabilities of a <CODE>Producer</CODE> Entity. This interface encapsulates all the information necessary to indicate the result of a BEST EFFORT operations on a <CODE>Producer</CODE> Managed Entity. The <CODE>ProducerKeyResult</CODE> is used in operations involving multiple <CODE>JVTProducerSession</CODE> entities, for example, in the deletion or creation of multiple <CODE>Producer</CODE> entities. This interface defines additional type-safe methods specific to getting and setting of <CODE>ProducerKey</CODE> attribute value, specific to this instances of this interface. A <CODE>ProducerKey</CODE> is a unique identifier attribute, present for each <CODE>ProducerValue</CODE> entity. It is used to identify a single <CODE>Producer</CODE> entity. The Type, ApplicationDN and ApplicationContext are included in super interface <CODE>ManagedEntityKey</CODE>, because a <CODE>primaryKey</CODE> is only unique within an application instance as given by the ApplicationDN running in a given naming system as given by the ApplicationContext::URL The <CODE>ProducerPrimaryKey</CODE> is the <CODE>primaryKey</CODE> representation of the <CODE>ProducerKey</CODE>. This interface is also the factory for creating the instances of <CODE>ProducerPrimaryKey</CODE>.