ࡱ > Y + bjbjWW = = s ] V V V V R R R 8 N . : : : : S e d Ik d f f f f f f $ u i R m Q l S m m q V V : : . q q q m V & : R : @ $ f t < V V V V m d q q u ] |
R @ : ' `H
AT o 8 EDUCOM/NLII Instructional Management Systems
Specifications Document
Version 0.5
Date: April 29, 1998
TOC \o "1-3" 1 Overview PAGEREF _Toc418494788 \h 5
1.1 Structure of Document PAGEREF _Toc418494789 \h 5
1.2 Status of Document PAGEREF _Toc418494790 \h 5
2 Introduction PAGEREF _Toc418494791 \h 5
2.1 Statement of Need PAGEREF _Toc418494792 \h 6
2.2 The Instructional Management Systems Project PAGEREF _Toc418494793 \h 6
2.3 IMS Stakeholders PAGEREF _Toc418494794 \h 7
2.4 Background PAGEREF _Toc418494795 \h 7
2.5 Design Assumptions PAGEREF _Toc418494796 \h 8
2.5.1 Content needs to be granular; systems need to be scalable PAGEREF _Toc418494797 \h 9
2.5.2 Desire for interoperability PAGEREF _Toc418494798 \h 10
2.5.3 Desire for customization and extensibility PAGEREF _Toc418494799 \h 10
2.5.4 Importance of collaboration PAGEREF _Toc418494800 \h 11
3 Technical Content PAGEREF _Toc418494801 \h 11
3.1 Assumptions PAGEREF _Toc418494802 \h 11
3.1.1 Multiple object models will continue to exist PAGEREF _Toc418494803 \h 11
3.1.2 CORBA and DCOM bridging capabilities will increase PAGEREF _Toc418494804 \h 11
3.1.3 Use of software agents will increase PAGEREF _Toc418494805 \h 12
3.1.4 Use of virtual reality and immersive environments for online learning will increase PAGEREF _Toc418494806 \h 12
3.1.5 Large instructional management systems will face problems similar to large transaction-based systems. PAGEREF _Toc418494807 \h 12
3.1.6 HTML remains the most cross-platform format PAGEREF _Toc418494808 \h 12
3.1.7 Distributing objects to users will increase PAGEREF _Toc418494809 \h 12
3.1.8 XML will become a dominant standard PAGEREF _Toc418494810 \h 12
3.1.9 Industry support for offline work will increase PAGEREF _Toc418494811 \h 12
3.1.10 Innovation requires broad areas within which producers in a marketplace can compete. PAGEREF _Toc418494812 \h 13
3.2 Requirements PAGEREF _Toc418494813 \h 13
3.2.1 Enable innovation PAGEREF _Toc418494814 \h 13
3.2.2 Support Extensibility PAGEREF _Toc418494815 \h 13
3.2.3 Utilize XML PAGEREF _Toc418494816 \h 13
3.2.4 Suppport dynamic generation of content and dynamic interaction with content. PAGEREF _Toc418494817 \h 13
3.2.5 Seed critical data types required to increase interoperability PAGEREF _Toc418494818 \h 13
3.2.6 Be implementable PAGEREF _Toc418494819 \h 13
3.2.7 Enable integrated environments PAGEREF _Toc418494820 \h 14
3.2.8 Support offline learning and training PAGEREF _Toc418494821 \h 14
3.2.9 Reuse existing standards PAGEREF _Toc418494822 \h 14
3.2.10 Enable scalable implementations PAGEREF _Toc418494823 \h 15
3.2.11 Enable loosely coupled systems PAGEREF _Toc418494824 \h 15
3.2.12 Enable the de-coupling of content and delivery systems PAGEREF _Toc418494825 \h 15
3.3 Design PAGEREF _Toc418494826 \h 15
3.3.1 Architecture PAGEREF _Toc418494827 \h 15
3.3.2 System Model PAGEREF _Toc418494828 \h 17
3.3.3 High Level Service Organization PAGEREF _Toc418494829 \h 17
3.4 Definitions PAGEREF _Toc418494830 \h 19
3.4.1 Containers PAGEREF _Toc418494831 \h 19
3.4.2 Meta-data PAGEREF _Toc418494832 \h 19
3.4.3 Profiles PAGEREF _Toc418494833 \h 19
3.4.4 Aggregation PAGEREF _Toc418494834 \h 19
3.4.5 Sequence PAGEREF _Toc418494835 \h 19
3.4.6 Management Software PAGEREF _Toc418494836 \h 20
3.4.7 Notification PAGEREF _Toc418494837 \h 20
3.4.8 Signposts PAGEREF _Toc418494838 \h 20
3.4.9 more. PAGEREF _Toc418494839 \h 20
3.5 Conformance PAGEREF _Toc418494840 \h 20
3.5.1 Content PAGEREF _Toc418494841 \h 20
3.5.2 Management Systems PAGEREF _Toc418494842 \h 20
3.6 Services PAGEREF _Toc418494843 \h 21
3.6.1 Groups/Users/Profiles PAGEREF _Toc418494844 \h 21
3.6.2 Sessions PAGEREF _Toc418494845 \h 22
3.6.3 Messages PAGEREF _Toc418494846 \h 23
3.6.4 Relationship PAGEREF _Toc418494847 \h 33
3.6.5 Property PAGEREF _Toc418494848 \h 43
3.6.6 Security PAGEREF _Toc418494849 \h 44
3.6.7 Persistence PAGEREF _Toc418494850 \h 47
3.6.8 Digital Commerce PAGEREF _Toc418494851 \h 48
4 Proof of Concept Implementation PAGEREF _Toc418494852 \h 48
4.1 Introduction PAGEREF _Toc418494853 \h 48
4.1.1 Scope and Status of Prototype PAGEREF _Toc418494854 \h 48
4.1.2 Platform requirements PAGEREF _Toc418494855 \h 48
4.2 User Interface PAGEREF _Toc418494856 \h 48
4.2.1 Logging In PAGEREF _Toc418494857 \h 49
4.2.2 Groups PAGEREF _Toc418494858 \h 49
4.2.3 Resources PAGEREF _Toc418494859 \h 49
4.2.4 Members PAGEREF _Toc418494860 \h 49
4.2.5 Communications PAGEREF _Toc418494861 \h 49
4.2.6 Backpack PAGEREF _Toc418494862 \h 49
4.2.7 Control Panel PAGEREF _Toc418494863 \h 50
4.3 Overview of Prototype Architecture PAGEREF _Toc418494864 \h 50
4.3.1 Management PAGEREF _Toc418494865 \h 50
4.3.2 Messaging PAGEREF _Toc418494866 \h 50
4.3.3 Content PAGEREF _Toc418494867 \h 51
4.3.4 Content Server PAGEREF _Toc418494868 \h 51
4.3.5 Profile Server PAGEREF _Toc418494869 \h 52
4.4 Prototype API Reference PAGEREF _Toc418494870 \h 53
4.4.1 user class PAGEREF _Toc418494871 \h 53
4.4.2 Group Class PAGEREF _Toc418494872 \h 54
4.4.3 UserProfile Class PAGEREF _Toc418494873 \h 55
4.4.4 Resource Class PAGEREF _Toc418494874 \h 55
4.4.5 SignPost Class PAGEREF _Toc418494875 \h 55
4.5 RMI servers PAGEREF _Toc418494876 \h 56
4.5.1 Coordinator RMI Interface PAGEREF _Toc418494877 \h 57
4.5.2 Channel Manager RMI Interface PAGEREF _Toc418494878 \h 58
4.6 Useful Classes PAGEREF _Toc418494879 \h 58
4.6.1 Message Class PAGEREF _Toc418494880 \h 58
4.6.2 Messenger Class PAGEREF _Toc418494881 \h 59
4.6.3 Resource Agent PAGEREF _Toc418494882 \h 60
4.6.4 CGI_MessageRouter PAGEREF _Toc418494883 \h 61
4.7 Prototype Utility Applications PAGEREF _Toc418494884 \h 61
4.7.1 Chat PAGEREF _Toc418494885 \h 61
4.7.2 Message Board PAGEREF _Toc418494886 \h 61
4.7.3 Message Service PAGEREF _Toc418494887 \h 61
4.7.4 Channel Spy PAGEREF _Toc418494888 \h 61
4.8 Resource Demos PAGEREF _Toc418494889 \h 61
4.8.1 History Test PAGEREF _Toc418494890 \h 62
4.8.2 Collaborative Graph and Monitor PAGEREF _Toc418494891 \h 62
4.9 Communicating with the Server: A Brief Tutorial PAGEREF _Toc418494892 \h 62
4.9.1 Posting HTML Form data to a Message Channel PAGEREF _Toc418494893 \h 62
4.9.2 Monitoring the Message Channel PAGEREF _Toc418494894 \h 63
4.9.3 Creating Signposts PAGEREF _Toc418494895 \h 64
5 Reference Schema PAGEREF _Toc418494896 \h 66
5.1 Meta-data PAGEREF _Toc418494897 \h 66
5.1.1 Module PAGEREF _Toc418494898 \h 66
5.1.2 Item PAGEREF _Toc418494899 \h 66
5.1.3 Tool PAGEREF _Toc418494900 \h 66
5.1.4 Course Catalog PAGEREF _Toc418494901 \h 66
5.2 Schemas for Assessment PAGEREF _Toc418494902 \h 66
5.3 Schemas for Performance Data PAGEREF _Toc418494903 \h 68
5.4 Schemas for Notifications PAGEREF _Toc418494904 \h 69
5.5 Schemas for Navigation PAGEREF _Toc418494905 \h 70
6 Reference Data Classes PAGEREF _Toc418494906 \h 70
6.1 Performance Data PAGEREF _Toc418494907 \h 70
6.2 Notifications PAGEREF _Toc418494908 \h 70
7 References PAGEREF _Toc418494909 \h 70
7.1 Dublin Core PAGEREF _Toc418494910 \h 70
7.2 OMG PAGEREF _Toc418494911 \h 70
7.3 ODMG PAGEREF _Toc418494912 \h 70
7.4 W3 RDF and XML PAGEREF _Toc418494913 \h 70
7.5 NIST RBAC PAGEREF _Toc418494914 \h 71
8 Contributors PAGEREF _Toc418494915 \h 71
9 Thanks PAGEREF _Toc418494916 \h 71
10 Special Thanks PAGEREF _Toc418494917 \h 71
11 Appendix A: Interface Descriptions PAGEREF _Toc418494918 \h 72
11.1 Group Service Interfaces PAGEREF _Toc418494919 \h 72
11.2 Session Service Interfaces PAGEREF _Toc418494920 \h 75
11.3 Messaging Service Interfaces PAGEREF _Toc418494921 \h 75
11.3.1 Origin of Interfaces PAGEREF _Toc418494922 \h 75
11.3.2 Interface Descriptions PAGEREF _Toc418494923 \h 75
11.3.3 CORBA IDL PAGEREF _Toc418494924 \h 133
11.3.4 DCOM IDL PAGEREF _Toc418494925 \h 151
11.4 Relationship Service Interfaces PAGEREF _Toc418494926 \h 151
11.4.1 Origin of Interfaces PAGEREF _Toc418494927 \h 151
11.4.2 The Base Relationship Model PAGEREF _Toc418494928 \h 151
11.4.3 9.4 Graphs of Related Objects PAGEREF _Toc418494929 \h 162
11.4.4 Specific Relationships PAGEREF _Toc418494930 \h 171
11.4.5 References PAGEREF _Toc418494931 \h 173
11.4.6 CORBA IDL PAGEREF _Toc418494932 \h 174
11.4.7 DCOM IDL PAGEREF _Toc418494933 \h 179
11.5 Property Service Interface PAGEREF _Toc418494934 \h 179
11.5.1 Origin of Interfaces PAGEREF _Toc418494935 \h 179
11.5.2 Interface Descriptions PAGEREF _Toc418494936 \h 179
11.5.3 CORBA IDL PAGEREF _Toc418494937 \h 191
11.5.4 PAGEREF _Toc418494938 \h 208
11.5.5 DCOM IDL PAGEREF _Toc418494939 \h 208
11.6 Security Service Interfaces PAGEREF _Toc418494940 \h 208
11.6.1 Origin of Interfaces PAGEREF _Toc418494941 \h 208
11.6.2 Interface Descriptions PAGEREF _Toc418494942 \h 208
11.6.3 PAGEREF _Toc418494943 \h 214
11.6.4 CORBA IDL PAGEREF _Toc418494944 \h 214
11.6.5 DCOM IDL PAGEREF _Toc418494945 \h 214
11.7 Commerce Service Interfaces PAGEREF _Toc418494946 \h 214
11.7.1 Interface Descriptions PAGEREF _Toc418494947 \h 214
11.7.2 CORBA IDL PAGEREF _Toc418494948 \h 215
11.7.3 DCOM IDL PAGEREF _Toc418494949 \h 215
12 Appendix B: The Role of RMI PAGEREF _Toc418494950 \h 215
12.1.1 Interface Descriptions PAGEREF _Toc418494951 \h 216
12.1.2 CORBA IDL PAGEREF _Toc418494952 \h 216
12.1.3 DCOM IDL PAGEREF _Toc418494953 \h 216
Overview
Structure of Document
The IMS Specifications document is divided into 3 primary sections. The first part is an introduction to the impetus behind the project and an overview of the project goals, the requirements and design assumptions. The second section of this document begins an introduction to the technical design decisions, rationale, and issues that have been addressed in the technical framework. Interspersed through this section is information about conformance. The final section is a series of Appendices that include the IMS Specification API; information, tutorials, and API reference about the prototype software developed to demonstrate IMS design concepts; and example data models for performance results, navigation events, and other types of information likely to be exchanged in an IMS conforming system.
Status of Document
This document is in draft form and is available for public comment until August 15, 1998. Comments should be directed to specs@imsproject.org. This document can be found at:
http://www.imsproject.org/specs.html
Introduction
"00011101010001100011000010101010010" --- W. Shakespeare (?)
Information in the digital world is broken down into bits and pieces represented in computer language as 0's and 1's. The above line could be the opening string of Shakespeare's Macbeth or it could be the representation of Mona Lisa's left eye in her famous portrait.
However random the combination of 0's and 1's might be, the abstraction of information into coded parts is meaningful when translated into some human understandable form, such as text or images. To say we live in an information society, though a clich, is not an exaggeration. The proliferation of information available at any given time is staggering. All of this information, from Einstein's theory of relativity to last night's basketball scores, can be reduced to 0's and 1's.
The power of computers for retaining and processing information, and the greater capacity for representing various types of information in digital form has created what has been called information overload. With all the information that can be readily available at any time and any place, two challenges arise: how to make sense of all this information and what to do with this information. In the first challenge, if the overload of information obscures any meaning, then the information may just as well retain its form as 0's and 1's. In the second challenge, information is not in itself powerful, but what can be done with the information is. When information can be leveraged appropriately, interactions can be richer and more productive.
In the information society, the challenges of making sense of information and using this information effectively has been described as the challenge of turning information into knowledge. This is a challenge felt in all areas where computers are being used as information processing and/or communication tools. It is a challenge of special interest to the education and training communities. The question many different learning communities face is how to support the interchange of information between students and mentors, between peers, and between individuals and the materials of the learning environment in meaningful ways. In other words, how to take the 0's and 1's, the bits and pieces, of the enormous amounts of information that can be generated, archived, reviewed, processed, shared, etc. and use this information toward supporting a more effective learning process.
Statement of Need
Using computers for education is not a new prospect although most efforts have been directed toward stand alone, context specific applications. The rise of networks, and in particular the Internet, has increased the interest in the use of computers as a channel as well as an environment for learning. Networked computers enable the learning experience to be a more collaborative experience than just a single student interacting with information on the computer. The Internet is heralded as a global, and most importantly, platform-independent network for supporting education through the creation, sharing, and distribution of information.
Schools, universities, corporations, and other organizations interested in promoting learning environments have recognized the potential of the Internet and are rapidly building, or have already built, a network infrastructure in order to capitalize on the world of resources. The next obvious step is to find and acquire valuable information. Many college campuses, for example, boast network connections in every room (both instructional and residential). But, a large majority of the content available serves primarily leisure rather than educational activities. To put it bluntly, the millions of dollars spent to connect students to the Internet are often put to use supporting online gaming or surfing for trivial facts and gossip.
In sum, although the technology for supporting learning environments has progressed, the proliferation of learning materials has often lagged behind. The development of computer based learning programs and content is an expensive prospect, both in terms of time and money, and the investment is often platform dependent. Furthermore, the power of leveraging information between different parts of the learning environment has not been fully tapped or explored. For example, on a college campus, student information systems, online library systems, learning platforms, all tend to be separate entities generating their own information in isolation from the others.
One of the main problems with learning materials on the Internet, more specifically on the World Wide Web, is the amount of noise that must be waded through before finding something of interest and relevance. Discovering effective learning materials on the web is a difficult process because there is no inherent structure or standards for describing the available content. The sheer volume of indexed pages limits the utility of full-text search engines for finding desired learning materials.
In addition, the extent of interactivity on the Web was initially limited to clicking through documents or filling out simple forms. As more interactive technologies have been developed to augment standard HTML, such as JAVA, ActiveX, JavaBeans, Javascript, and dynamic HTML, platform dependence has re-emerged as a problem. Online learning environments are utilizing these technologies to provide some level of interactive experience; however, the interactive content from one site can not easily be used on another site without significant expertise or time. Due to platform dependencies and lack of electronic commerce solutions, there are few incentives for developing and sharing interactive content.
In sum, there are three main obstacles for providing effective online materials and learning environments:
Lack of support for the collaborative and dynamic nature of learning
Lack of standards for locating and operating interactive platform-independent materials
Lack of incentives and structure for developing and sharing content
The Instructional Management Systems Project
In an effort to mitigate the obstacles mentioned above, the Instructional Management Systems (IMS) Project was created by Educom's National Learning Infrastructure Initiative. The project is an investment membership of academic, commercial and government organizations dedicated to facilitating the growth and viability of distributed learning on the Internet. The overall goal of the IMS Project is to Enable an Open Architecture for Learning. To this end, the IMS will release a technical specification and a proof of concept implementation that will enable the creation of quality learning environments and materials.
By creating a technical specification for learning materials and systems, the IMS provides a common framework for generating and leveraging information integral to the process of learning. A content developer may create materials that can be highly customized to unique learners' needs; a teacher may pull content from a variety of sources and integrate them into one system; a learner may be able to track their own progress and chart a personalized course through a training program. With a common base line, the different IMS Stakeholders can find innovative ways to add value to the learning environment.
As stated above, the directive of the document that unfolds in subsequent chapters is to provide an open architecture for learning. With this goal as the target, developers and consumers of online learning content, tools, and systems stand to accrue the following benefits:
Lower costs for the development and deployment of learningware
Improved quality of online learning materials and environments
Greater access to learning opportunities
More customized/flexible learning experiences
IMS Stakeholders
There are several stakeholders who will be affected by the IMS. We have defined these stakeholders in terms of the different roles involved in the process of learning. These roles are often performed by the same stakeholder: someone who is a teacher may also play the role of a learner and vice versa; similarly, a content provider may also engage in activities associated with the role of a teacher. These stakeholders in the learning process participate in a number of different communities: universities, community colleges, primary and secondary schools, training programs, testing certification agencies, and enrichment programs, to name a few.
One important phenomenon the IMS recognizes is the dynamic interplay between roles in the learning environment. We identify the main stakeholders, and some of their characteristics and activities, below:
Learners: will range in age, skill level, learning style, and motivation; may or may not be affiliated with a specific institution or organization; may learn as an individual or as a member of a group
Teachers: will possess a range of different teaching styles; may or may not be affiliated with a specific institution or organization; may teach as an individual or as a member of a group
Coordinators: may be an academic, professional, community, or private organization; may provide credit for the learning experience; may provide additional services for managing courses and curricula
Providers: may be an individual or a group; may or may not be affiliated with a specific professional organization or institution; may provide content and/or services; content provided may be original works (more specific role of an author) or may be aggregated works of others (e.g. publisher role); the provision of content and/or services will vary in terms of the mode of delivery and contracting arrangements
The IMS Investment Members, as a collective of educational and business organizations, are the architects of the system requirements for enabling online learning. In order to design a system that accommodates the various stakeholders needs, the IMS Partnership consists of representatives who play all the stakeholders roles.
Background
Although the audience for this document is intended as the technical development community, multiple user communities have played a part in the development of the IMS Specification. The first step toward gathering the information presented here involved a month long intensive requirements gathering process involving representatives of all the different stakeholder groups: developers, administrators and end users of online resources and environments. The result of this process was a set of core assumptions and requirements related to online learning systems and content. These assumptions and requirements have continued to be refined and evaluated through focus group meetings, conferences, and other interactions with end-users of the IMS Specification and conforming IMS materials and environments.
The interest from the end user community (namely, teachers, learners, and administrators of educational systems) in the IMS Specification revolved around the Specification's influence on the production of materials and systems that would be easy to use, interoperable, and customizable. Teachers want to be able to find materials easily, manage copyright restrictions, have more powerful tools for responding to learners needs, and have a greater quantity of excellent content and systems from which to create a customized environment. Learners want to have more authentic learning experiences and personal control over their learning process with multiple paths for gaining the skills and experience they seek. Administrators want to provide richer opportunities for their constituents, reach more students, lower deployment costs, and leverage the time and money already invested in various technologies.
In addition to interactions with the end-user community, the Specification has also been shaped by dialogues with the technical development community. Many of the investment members and the development network members who have also invested in the IMS Project have played a critical role in determining the direction and scope of the specification. Shortly after the requirements gathering process, a series of technical meetings with the investment members were organized around various areas of the specification. These meetings pulled from industry experts to explore various strategies and solutions for representing the user requirements in a technical specification and proof of concept prototype.
These technical meetings have continued throughout the development process of the Specification in order to create something that is sensitive to the current needs and trends in the industry while. At the same time, however, the Specification needs to be forward thinking and encourage rather than stifle innovation. From the development community, we were charged to create a Specification that built on top of existing standards, did not require excessive re-engineering of current tools or products, would be scalable and robust enough to grow with the industry, and would allow room for adding value to the base requirements.
Design Assumptions
From these exchanges with the user community, a conceptual model of online learning has evolved. Online learning is an additional medium for creating environments that are learner focused and driven. Learning online can be used for a range of purposes: from simply delivering content to remote places to participating in engaging interactive worlds. Therefore, the conceptual model of online learning that has driven the development of this specification is a multi-faceted evolving model.
One of the only constant characteristics of online learning is the constant state of change. People move in and out of different roles from teacher to student to author to publisher to administrator. Styles and theories of learning adapt to and shape the use of new technologies. Technology itself is constantly changing and at a very rapid pace. The predominant view of online learning now is one that is web-based, but this will grow to encompass a myriad of network and intermittent network configurations. The Specification, therefore, needs to account for legacy systems, of technology and processes. In addition, the Specification must not preclude but enable innovation.
Despite the inability to articulate one general picture or practice of online learning, at the core of our conceptual model is the recognition that learning, in all its various forms and mediums, revolves around interchanges in the form of communication or interaction. The main groups identified as IMS Stakeholders (learners, teachers, providers, and coordinators) form a tetrahedron of interchanges that occur throughout the learning process. There are two basic types of interchanges: between different stakeholders and within each stakeholder group itself. For example, there are peer to peer interactions among learners, as well as interactions between learners and teachers, providers, and/or coordinators. What passes between parties involved in an interchange is information, whether in the form of dialogue, a textbook, or a computer program. The IMS Specification focuses on providing a standard way for delivering and managing the information common in these learning interchanges.
Learning Interchanges
The above diagram depicts the variety of interchanges involved in a learning process.
Content needs to be granular; systems need to be scalable
An understanding of the learning process and environment as a system of interchanges suggests a model of interrelated parts. The idea that parts of the learning process and learning materials may be modularized supports the shift to a more diversified and learner driven environment where content may be reorganized fluidly across different learning contexts.
One example of modularization is the popularity of the course packet with specifically selected readings or exercises, over the static and standardized text book. This translates easily to a web environment where teachers or learners are free to pick content from the myriad of sources available. Another example of modularization in the learning process is the ability to offer a certification test at the beginning of a course that either passes the student or creates an individualized set of materials and exercises to reach certification. Learning programs do not need to be thought of only at the level of a four year plus degree or even a 16 week course. Learning programs may also be thought of as a collection of independent learning units allowing different combinations for different contexts and different learners.
The ability to break content down into modular parts and build it back up again within a management system will facilitate increased production of quality learning materials. Development of software tools for teaching and learning and their integration into the learning environment have historically been hampered by the lack of a commonly accepted specification that would permit them to be readily shared among institutions and across a wide range of technical environments. By supporting a development process that encourages the reuse of existing materials, development costs will decrease and the incentives for investing in content production with a longer life span will increase.
In addition to benefiting teachers, learners, and developers of online learning resources, the modular nature of these resources also benefits administrators of learning environments. For cost reasons and for comfort reasons, administrators may want to deploy a learning system at a very granular level and then scale up to a organization wide system. Many schools, training programs, and other educational organizations have already spent thousands or even millions of dollars to support the technical infrastructure upon which a learning environment can be built. Building this environment in pieces can help defray costs, as long as there is assurance that the various pieces being built will be compatible. Modularity can also help moderate human resource costs, such as technology anxiety or need for retraining. Most likely, online learning materials and systems will be championed by a small sub-set of early adopters within organizations. As others become more comfortable with the technology and as the technology and available materials improve, more people will be drawn to use the online environment and resources.
Desire for interoperability
A system of modular parts is not as desirable as a system of interoperable modular parts. Being able to break materials down into stand-alone pieces is useful, but being able to build these pieces into something new is more valuable. It is the interoperability of modular parts that allows developers to leverage their existing work and cut their development costs. Multiple authoring tools may be used to develop content that can then be pieced together. Furthermore, interoperability grants a sense of assurance that a tool built to work within one learning environment will work across multiple environments.
Ultimately, it is the end users of learning materials and environments who stand to gain from a Specification that promotes interoperability. Teachers and administrators of online environments can invest in new resources with a level of assurance that the tools and materials can be used by the widest population possible and across multiple contexts. Furthermore, interoperability expands the market which increases the quantity of available products. With more competition, producers are required to differentiate themselves based on quality. Finally, interoperable materials and environments leads to a more integrated and richer learning experience for teachers and learners. A communication tool, for example, can leverage information already collected about a group or an individual to allow for personalized experiences.
We should note, however, that although a goal of the Specification is to promote interoperability, this will not eliminate the potential for incompatible technologies or applications. The degree to which external applications (e.g. plug-ins or helper applications) are needed to run content is within the creators discretion (although the Meta-data Specification will help users identify what content requires additional hardware or software).
Desire for customization and extensibility
The desire for customization is both complementary to the desire for interoperability and at odds with it. On the one hand, a customized system is permissible through the unique combination of interoperable parts. On the other hand, interoperability requires a level of commonality and standard procedures that limits the extent of total customization.
Overall, however, the Specification is being written so as to allow for customization in implementation. The Specification is descriptive rather than prescriptive so that developers are ultimately restrained only by the needs of their user communities. The core requirements and features of the IMS Specification can be implemented in multiple ways and developers can further add customized features to increase the value of their products. The amount of customizability these products have in the end-users hands is generally determined by the market and provided by the content and system developers.
A guiding principle in developing the Specification is that the requirements for online learning environments will evolve as the way people learn shapes the technology and the technology shapes the way people learn. Furthermore, as indicated previously, there will always be multiple learning styles and needs. Therefore, the Specification aims to provide a common base from which different learning communities can develop their own requirements, policies, and specifications. The Meta-data Specification, for example, seeks to articulate a base set of common descriptive terms for locating and managing learning resources. This commonality allows for communication across learning communities and contexts. We fully expect, however, that different communities of practice will extend the Meta-data Specification to include terms unique for their own community. Best practices with Meta-data and with other aspects of the Specification may eventually amend the general Specification.
Importance of collaboration
The non-prescriptive nature of the Specification precludes orienting the technical support toward any one pedagogical style or teaching method. However, we have conscientiously included support for communication and collaboration. The educators in our requirements gathering process and focus group sessions all stressed the importance of communication for the learning process. The learning interchanges mentioned above could be considered interchanges of a conversation. The conversation occurs between the learner and the environment consisting of people and other resources.
Even self-directed learning programs have some type of interaction between the learner and the body of knowledge or skill sets the learner is trying to acquire. In the workplace, where learning is being considered more of on-the-job performance support versus out-of-the-office training, the rise of groupware tools speaks to the importance of collaboration for ongoing learning. Many existing instructional management systems may be considered an extension or applied use of groupware technology.
In traditional classroom environments, the high potential for interaction between peers and mentors is one reason why many have looked upon online learning with concern. The need for supporting rich interactions and exchanges is viewed as an essential aspect of the learning process. Therefore, the Specification provides explicit support for synchronous and asynchronous communication and the use of shared artifacts and tools for collaboration.
Technical Content
Assumptions
The following assumptions about the current and future state of the technical environment in which IMS implementations will operate have shaped the development of the IMS specifications.
Multiple object models will continue to exist
Currently two Distributed Object Models dominate in the marketplace: Microsoft's Component Object Model (COM) and the Object Management Group's (OMG) Common Object Resource Broker Architecture (CORBA). Both of these Models support Java and CORBA will support Java/RMI. Each of these Object Models supports a Component Model: ActiveX in COM and JavaBeans in CORBA
CORBA and DCOM bridging capabilities will increase
The computer industry is demanding of OMG and MS interoperability of COM and CORBA-based objects. Bridges already exist and MS's active participation via agreements with IONA and other CORBA vendors will increase the capabilities of these bridge products. The existence of these bridges will allow IMS to be technologically neutral thereby allowing developers of component-based content to choose whichever component model that is appropriate for their target audience.
Use of software agents will increase
Software applications that act on the behalf of a user to accomplish some educational or training purpose will increase. Intelligent tutors that augment the role human mentors or authors play in creating and facilitating an educational experience can be viewed as Software Agents.
Use of virtual reality and immersive environments for online learning will increase
Currently the Web browser is the window onto Internet content. With the advent of higher bandwidth networks, improved standards in network-based multimedia architectures, and ubiquitous higher performance graphics capability in desktop and laptop computers, the use of immersive environments with high quality virtual reality will be used increasingly in online education and training.
Large instructional management systems will face problems similar to large transaction-based systems.
Large management systems with tens of thousands of learners and very large numbers of granular content will face technical scaling challenges similar to those of large transactional systems.
HTML remains the most cross-platform format
Rendering content in HTML is the most cross platform solution available today. However, it's lack of interactivity limits its utility in creating compelling online teaching and learning contexts.
Distributing objects to users will increase
Sending object-based content to the user's desktop computer is problematic due to Java virtual machine differences in Netscape and MS web browsers. Network bandwidth, firewalls, and varying performance of machines also contributes to difficulties in deploying object-based technology to the desktop. However, these problems will be resolved over time in a broad Internet content and in some situations, such as company Intranets, the object deployment problems may be very minor and therefore feasible.
XML will become a dominant standard
XML will have a significant impact on the computing marketplace and will be the standard interoperable syntax for expressing data. XML will also be used to represent collections of objects for transmittal via ubiquitous protocols such as SMTP and HTTP.
Industry support for offline work will increase
Learning and training with network-based resources in an intermittently connected environment will be commonplace. Business travelers, students with laptops, and users with per minute communication tariffs, such as is common in Europe, all have practical and financial reasons to work in an offline mode, then reconnect to continue their learning. The asynchronicity of this behavior is not limited to learning and training. Various industry-wide technical organizations are addressing the technical infrastructure required to support intermittent connections. For example, W3C is addressing standardized caching solutions for web browsers. OMG and Microsoft are working towards support for Asynchronous Method Invocations, a necessary component required for object-based software to work in an offline mode. These new services will become transparent through their incorporation in network services layers, operating systems, and web browsers.
Innovation requires broad areas within which producers in a marketplace can compete.
A vibrant, standards-based marketplace in online learning and training requires that developers of content, services, and management systems have very broad areas within which to innovate and compete. The use of the Internet in training and learning is so new that it is reasonable to assume that the future of online learning and training will be very different than what we can predict today.
Requirements
Enable innovation
The IMS Specifications are silent on issues of user interface, quality, and teaching/training processes in order that brisk competition in the marketplace will produce high quality, affordable content, effective user interfaces and instructionally sound learning processes.
Support Extensibility
Syntax, semantics, structure, and functions should be extensible allowing for specialization by different groups, vendors, and knowledge domains. This applies primarily to meta-data, structured data, and programmatic interfaces.
Utilize XML
IMS Specifications will use XML as the serialization syntax for data and objects.
Support dynamic generation of content and dynamic interaction with content.
Content developers and publishers will increase their use of technologies that support dynamic generation of content in lieu of unmanageable collections of static web pages. The use of interactive content on the client will increase. Correspondingly, Web-based content, such as HTML content that requires a round-trip post and response approach with a Web server will decrease in relation to more interactive content. IMS should support this trend through runtime interfaces that allow for client side and client-server transactions of varying levels of granularity and complexity.
Seed critical data types required to increase interoperability
Extensibility is the ability of people to provide specializations. As specializations increases, interoperability decreases.
Extensibility is primarily a technical issue that is either present or not in a specification. Interoperability is part technology but equally or more so driven by the conformance a community of best practice follows in their reuse of the group's specializations in the development of new content.
The IMS Specification should facilitate interoperability in the context of extensibility by providing best practice starting points, such as schemas for content meta-data drawn from collaboration with experts and users.
Be implementable
Define technical specification that allows a marketplace of online learning to thrive through the active participation by developers representing a broad range of authoring skill levels. The range of programming skills will vary from document construction, with word processors, spreadsheets, and presentation programs; visual construction; scripting; and low-level programming in languages such as C++ and Java.
Enable integrated environments
Enable an IMS environment made up of people, service organizations, tools, content, and data about learners all linked together via the Internet through permanent or sporadic connections. See Figure 1.
Figure 1
People include students, employees, and mentors (i.e. teachers). Mentors might also be smart software, such as intelligent tutors.
Tools include applications for collaboration, general-purpose content analysis or generations, such as a spreadsheet or graphing tool, administrative, and authoring.
Service organizations include schools, training departments, publishers, associations that act as buying clubs for content for their members, digital libraries, content collection companies that provide reviews and analysis of content, internet search engine sites that allow for searches of learning content, and data repository companies that provide hosting of learner data. The types of service organizations will expand as the online marketplace grows.
Learner data is data information about the student learner including preferences, such as learning styles, personal information, such as name and email, performance information, such as what grades and degrees the student has received, and portfolio information, such as links to content the learner may have created in past learning processes. The types of information tracked about a student is expected to increase.
Content is the learning materials that a learner uses. The materials can be online, such as web pages and objects, or they can be online references to physical resources, such as textbooks, audio tapes, etc.
Support offline learning and training
The specification should, were possible, address offline work. Efforts of the industry should be leveraged where possible.
Reuse existing standards
The IMS specification will reuse relevant industry standards to achieve its design goals and will do so in ways that allow for freedom of implementation. That is to say, the IMS Specifications will not pick winners or align itself with anyone technology camp. If an existing standard supports IMS requirements and the standard provides sufficient detail to facilitate implementations, then it will be used, perhaps with some changes to make it implementable in the prevailing industry technologies.
Enable scalable implementations
The specification will avoid creating architectural bottlenecks or impediments to building and deploying scalable implementations.
Enable loosely coupled systems
Loosely coupled technical architectures can evolve more easily as individual pieces can be changed without breaking other pieces. The IMS specifications are loosely coupled in order to support evolution without creating significant update burdens on developers of IMS-conforming content and management systems.
Enable the de-coupling of content and delivery systems
Figure 2
Enable content from multiple authors to work with multiple management systems without recoding.
Design
Architecture
The following diagram illustrates the overall organization of an IMS System. It shows how an IMS Server interacts with authoring tools, search engines, content servers and profile servers to create a personalized and powerful learning, teaching, and authoring environment.
The connections between various parts of the Model represent the various types of data exchange and communication in the IMS system.
1. A Search Engine may use meta-data information to query a Content Server for specific kinds of learning material.
2. A Search Engine may query a Profile Server to find persons with desired skill certifications.
3. An authoring tool may query a Profile Server for preference and performance data to customize its presentation.
4. A Search Engine can obtain course meta-data from a Content Server at an organization hosting an IMS server.
5. Authoring tools may exchange content with an IMS Management System.
6. Authoring tools may interact with content servers to find or provide content and content meta-data.
7. A content server may provide content material to an IMS Management System.
8. There will be many content servers reachable by search engines.
The second diagram presents a more detailed view of the IMS Server System showing how it interacts with user clients and organizations through a standard set of IMS interfaces. These interfaces allow clients to access IMS services through HTTP, RMI, DCOM or CORBA bindings. In the case of HTTP a CGI proxy is provided to mediate communications with the Management System from web pages using HTML POST commands.
System Model
High Level Service Organization
The conceptual design of the IMS Specifications addresses the following five aspects of the online learning marketplace.
Meta-Data
Meta-data are fields and associated values that describe a physical or electronic resource. IMS has defined an extensible collection of meta-data for educational and training resources including, content, performance items, performance results, personal information, and certification information.
Dictionary and Types
For content meta-data, IMS has defined a dictionary and a collection of required and recommended terms for classifying different types of learning resources.
Meta-data Information Site
The IMS has developed, with the National Institute of Standards and Technology (NIST), a repository of meta-data terms that will be a resource to the broad community of content developers, users, and service providers to facilitate the identification and reuse of common meta-data terms. Common terms simplify the process of tagging and discovering learning resources via Internet-based tools. Common terms also enable the development of technologies that can enhance an online learning experience through automated and intelligent processes (i.e. smart agents, intelligent tutors).
The IMS Meta-data Information Site (temporary url: HYPERLINK http://sdct-sunsrv1.ncsl.nist.gov/~boland/ims.html http://sdct-sunsrv1.ncsl.nist.gov/~boland/ims.html) also includes collections of additional terms that are specialized from the core IMS sets by industry and knowledge domain groups.
The site describes the collections of meta-data terms in both XML and in a variety of object bindings. IMS specifies that content meta-data, when referring to web pages, be stored in a separate file in XML format until browsers include support for inline XML.
Relation to Services
Programmatic access to meta-data is accomplished through the Property Service, described in the Services section of this document and Appendix A..
Content
Content interfaces define the actions and responses that IMS-conforming content may perform. In some cases, such as with static HTML content, the content's support of the actions/responses associated with a particular interface may be inferred by meta-data values and mediated by an IMS-conforming management system.
Content can be an educational objectives or aggregations of objectives. It can be an educational module or aggregations of modules that have an educational or training intent. On the other hand, content can be something as simple as a word or a picture.
Curriculum Granularity
A meta-data field is provided for authors to designate the scope of content within a curriculum. E.g. Course, lesson, topic, etc.
Execution Environment and Technology
Content can run on the client or on the server. Content can be implemented in whatever technology an author desires. E.g. html pages, ActiveX controls, Javabeans, Javascript, executable applications requiring plug-ins, etc. For html-based content, conforming IMS management systems will search and replace IMS tokens to dynamically localize html content for that specific management system's CGI URL and the student's group and session.
Relation to Services
Content can makes use of all of the services described in the Services section of this document and Appendix A. The Relationship service is used to represent containment of content within other content and the sequencing between content.
Management Systems
The management interfaces support interoperability and deployment of any IMS-conforming content to any IMS-conforming management system. Management interfaces will form the skeleton of instructional management system products that conform to the IMS specification for management software. The IMS specifications for management software do not specify user interface requirements. It is expected that management software will be developed with user interfaces appropriate for the market that the developer wishes to address.
Relation to Services
The management system implements the IMS Service Specifications that IMS conforming content use.
Profiles
Profiles are mobile, user-controlled collections of personal and educational data. Portfolio information may be stored or referenced within the profile. Preference information such as learning styles, default meta-data selections may be included. An IMS Profile for a user may include both learner-specific and author-specific information since an individual can be both a teacher in one context and a learner in another. The granularity of the educational or skill certifications stored in the profile is not specified. Skill certifications can be digitally signed or not.
Relation to Services
Profiles are part of Groups/Users/Profiles service. Manipulation of the profile server data is via the Property Service.
External
External interfaces provide a means by which IMS-conforming content and management software can leverage external systems that are likely to be found in an online learning environment such as student information systems, registration systems, electronic commerce systems, and libraries.
IMS is developing a back office implementation guide as a reference for IMS management system developers to understand the nature of back office systems, with respect to latency of transactions etc., and which parts of the IMS object model are affected. See http://www.imsproject.org/specs/backoffice.doc
Definitions
Containers
Containers encapsulate a given amount of content. Content may consist of primary elements (text, graphics, movies, tools) and/or additional containers. In this way, containers may be added together, or aggregated, within a larger container. In order to facilitate the location, storage, and retrieval of containers, each container will have a set of meta-data fields.
Meta-data
Meta-data is data about data. More specifically, it is descriptive information about a learning resource for the purpose of finding, using, and/or managing this resource.
Profiles
User profiles are mobile, user-controlled collections of personal and educational data including personal information, performance information, and preference information. This data represents a rich resource that a user can draw on to facilitate, customize, and manage his or her learning experience(s).
Aggregation
Combining learning resources or elements together so as to create a new learning resource is considered Aggregation. Whether or not a learning resource may be aggregated with other resources depends upon its use rights determined by its creator and/or user rights agent. The opposite of Aggregation is Disaggregation which entails breaking down a learning resource into multiple learning resources.
Sequence
Sequences for learning resources can be defined at two levels. Within a learning resource, the creator may specify a sequence between the different elements that make up the learning resource. Between learning resources, for example the resources gathered for a group, the group administrator may also define a sequence for navigating through the resources.
Management Software
Management software is a collection of programs to manage the session, resources, tools, and members of a group.
Notification
A notification message is sent from an application to an event channel when a user has reached an enabled signpost or triggered an event that another user has requested to be notified of.
Signposts
A signpost is an object associated with a marked point in an application. When the marked point is reached by a user, the signpost is consulted to determine how the notification should be sent and to whom.
more.
Conformance
A conforming implementation will support the interface methods and properties described in this specification. Conformance tests and a testing process are underdevelopment in collaboration with the National Institute of Standards and Technology (NIST).
Testing will include a combination of self-testing and strict conformance testing. Strict conformance tests will be developed for areas where the underlying technology is not changing rapidly, e.g. meta-data. Self-testing and interoperability guarantees will be recommended for areas where significant industry change is expected, e.g. distributed object services.
The use of an official IMS logo, designating conformance, will be made available to those products that have successfully completed conformance testing.
Except for self-testing, conformance testing will be done initially by the IMS Project, but will transition to internationally sanctioned testing laboratories. The IMS Organization will issue certificates for products that have successfully passed conformance testing. A control board will be established for conformance testing dispute resolution.
Content
Content developers may choose to support whichever IMS interface bindings are appropriate for their intended market.
Management Systems
Developers of IMS-conforming Management Systems must support one or both of the following sets of interface bindings. This is termed the "two-island" approach. Existing and emerging component bridging products will allow management system developers to support both.
Island A
HTTP
COM
Island B
HTTP
CORBA
RMI
Services
Groups/Users/Profiles
Group Service Description
Key Features
The IMS is about creating virtual learning environments. The types envisioned range from on-line versions of traditional classrooms with twenty or thirty students participating that is augmenting instructor led classroom experience, just-in-time classrooms of one pupil that are created for on-the-job learning scenarios, immersive simulation environments, and many others. The challenge to the IMS is to come up with a programmatic interface that will allow sufficient generalization for third party tools to be created while leaving wide latitude to implementations. These implementations will be targeting specific markets and providing competitive differentiation. By far the most prevalent metaphor for managing the interaction of people, content, and tools in the market is the nestable Folder, or Room in the Multi-user Object Oriented ( MOO ) world. The IMS chose this abstraction since it allows a direct mapping to many, many products in the marketplace, and because it provides a straightforward way of envisioning the types of learning environments asked for in the requirements.
In the IMS, as in many groupware products today, users participate in a group in the context of a particular role. For example, in the Biology 101 group, Mary Clark may be playing the role of a student. In this respect, she will only have access to those items that are granted to students. In addition, students are an identifiable group of people, so the teacher can send an e-mail to all of the students without having to address them one-by-one. In the Biology Study Group contained in the Biology 101 group, Mary plays the role of Group Leader. As such, she is able to invite new users into the group, add resources to the group, and otherwise manage the group.
The Security Service, in the form of IRole, provides the roles that we are describing here. The role assignment system takes advantage of the inheritance of roles to make the assignment of privileges as generic as possible while allowing access control to be maintained at a fine grained level. For example, an administrator of an IMS system will create an object supporting IRole for Group Leader. Group Leader will be given certain permissions, such as adding users and resources to groups. When assigning a particular user to a role in a group, the user actually is assigned to an inherited version of the role. In our study group example, Mary Clark plays the role of BiologyStudyGroup::GroupLeader. This way, within the Biology Study Group she does everything a Group Leader can do. However, within any other Group, her role is not given any permissions.
Group Service Structure
Levels of service
The group service requires all of the interfaces to be implemented except for ICertification.
Interface Summary
InterfacePurposePrimary ClientsIMSGroup::
ICertificationDefine the behavior of a self-managing certification, for example, a registration for the bar or a medical license.Clients which must validate a users certification before allowing them to proceed.IGroupDefines the abstract behavior of a virtual classroom or other online collaboration area.IMS client programs.IUserDefines the abstract behavior of a person registered in an IMS system.IMS Security managers and resources which specialize the user experience based on the specific user.IResourceCoordinatorSupports the creation of a virtual school. Contains operations for creating and registering users.IMS client programs.IMessageChannelManagerSupports the creation and management of messages channels for the group. These channels are integrated into the security of the group.Resources and Tools within a group which must emit or consume information via messages.Sessions
Session Service Description
Key Features
Ensuring a rich, consistent user experience is a goal of the IMS. The IMS is not interested in defining what that user experience is, though. We want programs that provide the user experience to have the ability to present groups and content from multiple IMS locations and vendors in one consistent view. This view may be via a web browser, or a specialized client program for desktop PCs, or even a specialized training interface for an embedded system, such as the display screen on a Global Positioning System ( GPS ) receiver. In order to do this, all user interface elements, as well as housekeeping activities such as login and preference storage, must be allowed to happen outside of the context of any one IMS management system.
DIAGRAM OF DIFFERENT USER EXPERIENCES
The IMS Session service is designed to allow this de-coupling of user experience from IMS content systems. The session service utilizes a Session object to either present the user with a single logon, or coordinates with the users operating system to obtain the user credentials that the user acquired when he or she logged into the computer ( such as in Window NT or the MIT Kerberos environment ). The Session object then steps through the list of IMS content servers that the user has configured, attaching to each one in turn so that the user can browse them.
An important aspect of a consistent user experience is the resumption of a users session after they have suspended it. This can be because of taking a break, or of moving from home to school. In addition, the user may resume their session using a different user interface device, such as moving from a desktop computer at home to a Personal Digital Assistant at school. Many existing collaboration systems provide this level of consistent user experience. The Microsoft Messaging API ( MAPI ) allows users of Microsoft Outlook ( a MAPI Client ) to connect and browse in a unified manner Microsoft Exchanges folders, Fax Service Folders, Voicemail Folders, and Workflow Folders ( each of these are MAPI Message Store Providers ).
Session Service Vs other options
A major decision facing the IMS was whether or not to de-couple the user experience, or session, management from any single IMS server. The two choices available to us are examplified in the groupware marketplace today. Most web servers implement session management inside the web server. Web browsers make some of this transparent to the user by the use of cookies and certificates. However, there is no session-oriented collaboration between a browser and the web servers to which it has connected. On the other hand, Microsoft Exchange and other Messaging API ( MAPI ) compliant products move the role of session management squarely in the camp of the client program, such as Microsoft Outlook. On startup, such a program retrieves a users security information and then tries to connect to the message stores that the user has configured. It then usually provides a unified User Interface for the user to browse through the disparate message stores. This later model is the one chosen by the IMS.
It is expected that many web-oriented IMS products will likely have a single web server proxy for this session management, possibly even providing a common User Interface for disparate IMS systems that a user is connected to. In time, we expect both these server-side products as well as integrated desktops and immersive worlds to be de-coupled from the content sources that they allow a user to navigate.
Resolution of technical issues
Session Service Structure
Levels of service
There is only a single level of service in the Session service. This service is completely contained in the ISession interface.
Interface Summary
InterfaceIMSSession::PurposePrimary ClientsISession
Represents a program managing a clients user experience in the IMS.Client programs such as browsers or integrated desktop environments.Messages
Origin of Interfaces
The following information is based entirely on the Object Management Groups proposed specification of the Common Object Services Notification Service. The only changes that have been made, other than the addition of IMS context information, is the harmonization of interface signatures with the rest of the IMS and the possible removal of some low level CORBA dependencies.
Message Service Description
Key Features
The IMS Messaging Service provides the communications backbone that allows for dynamic collaborations between learning content, learners, and facilitators. The key elements of a messaging service are channels, managers, quality, and transactions. Message channels are like TV channels in that they allow for the broadcasting of information to multiple people without the originator having to link up separately with each person. Event managers keep track of the different message channels that are active and the kinds of information being carried on each channel. They help sources and users of message information to connect to the appropriate channel. Quality is information that tells a channel about how to treat a particular message, such as This message should last for two days before being deleted or This message must get to all possible recipients. Transactions are bounded activities that must happen as a unit. Such a bounded activity might be the messages that transmit a students grades on different sections of a test. It is important that the grades for sections 1 and 2 both get to any evaluators. The two messages can be bound up in a transaction so that the publisher of this information can be confident that both parts will reach anyone who is evaluating the grades.
Learning materials need to communicate with one another in order to provide a rich environment to learners and teachers. For example, a teacher may be facilitating thirty students progress through an on-line tutorial. Since the students are distributed by geography and possibly time, the teacher cannot directly observe the students terminals to assess how the student is doing and provide feedback. It is necessary for the tutorial to communicate pertinent information about how a student is doing. Such information might be that a student has started the tutorial, the student has passed a milestone in the tutorial, or that the student is repeating a difficult section of the tutorial and may need help. This type of information the author of the tutorial can predict. How that information is used and by whom it is used, however, is unpredictable when the author is creating the tutorial. This is where events, or messages, can come to the rescue.
In an event model, an event source such as our tutorial emits some information. It is up to event users to actually do something with an event. Lets use our example in more detail to show the picture. Lets say that our tutorial wants to tell the world about various types of of navigation a student is performing in the tutorial. Those navigation types are Start, Stop, Section Complete, and Section repeat. We can represent these by the following structure:
NavigationEvent
{
EventSource ( in our case Tutorial )
EventType ( in our case Navigation )
EventAction ( either Stop, Start, Section Complete, etc )
EventUser ( a student, say Mary )
EventComments ( Some descriptive information )
}
The Tutorial now has a well-known way to tell the world about what is going on inside of it. In an IMS system, the Tutorial program tells the world about this information this way:
PSUEDOCODE INSERTION FOR BASIC TYPED PUBLISH
This information allows some third party to create a program that will make use of the event. Lets take two: a class participation program that tracks every students activity inside the virtual classroom. This program gives the teach a rough idea of who is participating and who is not. The second program is an extra help watcher that the teacher uses to notify her of students having trouble.
The first program wants to register for all Navigation events that happen in a virtual classroom. It then takes these events and puts their information into a log that the teach can review later.
PSUEDOCODE INSERTION FOR REGISTER BASIC TYPED SUBCRIBE
The second program also wants to register for Navigation events, however, it is really only interested in Navigation events that have an EventAction of Section Repeat so that it can notify the teacher. It can do this two ways. The first way is to register for all navigation events and then as it receives them, it can look at the EventAction field and only pay attention to those events with an EventAction of Section Repeat.
PSUEDOCODE INSERTION FOR A HANDLER BASED FILTER
If there are a bunch of programs listening to Navigation events and are only interested in Section Repeat actions, having each one filter the events separately is rather inefficient. Instead the program send a filter along with its registration for events allows whoever is managing the broadcasting of events to apply the filter and only send events to the people who are really interested in those events.
PSUEDOCODE INSERTION FOR REGISTER TYPED SUBSCRIBE WITH FILTERING
Implementation Scenarios
Integrating Collaboration Tools
Although there are no explicity recognized Tool objects in the IMS Design specifications, it will be common to find specialized Resources such as notebooks, schedules, discussion lists, chat spaces, calculators, and other such objects that serve users in this capacity. Tools, like all Resources, operate in the context of the Group to which they have been added. As a Resource object, they contain references to two other important objects: their user's current Group and Session. Using the Group reference, tools can acquire a complete list of group members, lists of other resources available to the group, the names of the group leaders, the group's private message channels, and much more. By querying their user's Session object they can determine the user's profile, email address and preferences. With this specialized knowledge IMS tools can configure their options and operations to provide optimal service to their users.
A chat tool, for example, might use one of the group's existing message channels to support its communication protocol, and it might use a member's browsing preferences to present either a text or avatar based interface. A collaborative, multi-user frog dissection program might use one of the group channels for data exchange or create its notification channel for sending participation notices and session logs to the group leader. Discussion lists will use their knowledge of group membership to control what messages are listed. Tools may also grant or deny use privileges based on their ability to ascertain a user's role in the current group context.
To demonstrate how all this might work, let's imagine that Sally is using a Chat Tool in the context of her Biology group. After some moments of interacting with the tool and talking to other members of her class, let's suppose that she asks the Chat Tool to email her a transcript of the discussion she has just had. Here, in pseudocode, are the steps a Chat Tool might take. First, the tool might use the Session object to help ascertain Sally's email address:
session = this.getSession();
user = session.getUser();
email = user.getPreferences().getEmail();
Then the Chat Tool might construct a Notification message adding this address to the Filterable portion of the message body. (See following sections for further discussion of structured event messages.)
message = new Notification();
message.setEmailTo(email);
message.setBody(transcript);
Then the Chat Tool might find the name of the Biology group's Notification channel.
group = session.getGroup();
chan= group.getNChannel();
Finally the Chat Tool might open the notification channel and post the message.
channelmanager = group.getChannelManager();
connection = channelmanager.openChannel(chan);
channelmanager.send(connection, message);
The message sent to the group's Notification channel might, in this example, be picked up by an appropriate emailing program that is filtering notification messages looking for "EmailTo" fields.
Tracking and Notification
A central requirement for the IMS Management System is that it support asynchronous messaging, notifications, and data exchange between collaborating resource applications. To achieve this goal each IMS group is required to have access to a Message Channel Manager capable of registering applications to send or receive structured event messages of well known types. Although applications are permitted to open channels and exchange information in proprietary ways, it is expected that the greatest degree of interoperability between resource applications and the management system will result from the shared use of conventional message types, either as structured events or as full blown message objects.
Here is a diagram of a generic structured event message. It contains a header and a body. The body may contain content of any kind. The header is only required to supply the name of an event type and an identifier for the specific message event. Optional headers permit the inclusion of time stamps, priority indicators, level of persistence, network routing paths and other name value pairs specified in the reference API. The filterable section of the body provides properties and values that allow receiving applications to filter out messages in which they have no interest.
Here is an example of a special kind of IMS Structured Event Message, the Notification Event Message. It is a straightforward message TO someone in particular FROM some application or resource. The event type is "Notification" and the event name is a unique identifier for the message. The content of the message body is unspecified and could be anything.
Messages in the IMS system are organized into an Event Type inheritance hierarchy. Part of this hierarchy is illustrated in the example below showing how Navigational event messages extend, or inherit from, the simpler Notification event message type. This example is for illustration purposes only, the exact hierarchical structure is still work in progess.
Using Structured Events Messages
Sending and receiving structured event messages in an IMS environment will be done by using a set of Message objects. Each of these objects correspond to one of the IMS recognized event types, such as Notification, Navigation, Assessment, Performance, Collaboration and Administration. These Message objects are similarly arranged in an inheritance hierarchy descending from the root Message object. Objects further down the hierarchy will have additional methods for setting and reading specific header values, filter values, and body values.
An Example
Let's suppose that a student in a Biology class reaches a certain point in a Frog Dissection resource application marked by an internal signpost and that the application wishes to notify the group leader of this event. This event is a special kind of Notification event called a Navigation event. The application first creates a NavigationMessage object and gives it a name for future reference and possible acknowledgment return messages.
message = new NavigationMessage("SignPost-4496");
This kind of message automatically includes a TimeStamp field set to the time the message is sent and a delivery priority set to a default of 10. (The highest priority is 0, the lowest is approximately 64,000). The application decides to reset the priority and assigns values to the Filterable data fields.
message.setPriority(5);
message.setTo(GRP-LDR); // Message is for the Group Leader
message.setFrom("R-4337"); // Resource Identifier
message.setRe("SIGNPOST"); // Contents of Body
Let's assume that the Frog Dissection Resource is communicating with the IMS Management System over the general Notification channel for the Biology 101 group. In order to send the constructed Navigation message to this channel, the application will need to create an IMS ResourceAgent object. The ResourceAgent object is a convenient way for Resources to communicate with the Management System. The ResourceAgent object is not, at this time, part of the standard IMS interfaces. It is only a suggested simplification for clients. It contains methods for querying the system to determine information about the resource's group and user and provides an interface to the group's Message Channel Manager. The application can create a new agent and use it to get a reference to the group notification channel.
agent = new ResourceAgent(this.name, this.group);
nchannel = agent.getNotificationChannel();
The application then sends the message to this channel.
agent.sendMessage(nchannel, message);
On the receiving end we can imagine that the message is picked up by some application that is expressly interested in processing sign post information from this particular resource. This application, let's call it the "Sign Post Monitor", has registered with the Biology 101 group's Message Channel Manager to listen solely for Navigation events. The monitor employs a further filter to select only those navigation events that constitute signposts and come from resource "R-4337". It does this by checking the name and value fields in the filterable part of the message body. Finally, because it knows that this message is about sign posts it knows to look in the content part of the body to discover WHO reached the particular sign post.
Message Service Vs other options
The IMS needs a message service that will allow simple and complex exchanges of messages over the network. These exchanges should be secure, atomic, and durable. There are many event models in place in todays applications. COM and Java both utilize a form of event delegation. Sources of events simply worry about emitting the event information. Subscribers of the event information actually implement features that handle the event.
This is what we want, however, the models usually involve a direct connection between the event producer and the users. Both environments, however, lend themselves to the creation of adapters. The conceptual model of adapters presented here is taken from Client/Server Programming using Java and CORBA by Robert Orfali and Dan Harkey, Second Edition, 1998. Adapters intersperse themselves between an event producer and its consumers via the message channels discussed above. Generic adapters allow messages to be mapped onto method invocations on the target program instead of simple event handlers. Wiring adapters are a specialization of this that allow visual tool builders to create dynamic invocations between two components by dragging a wire connection between them. Distributed adapters allow method invocations on remote objects to be mapped to a particular message. In addition, Filtering adapters allow messages to be pre-filtered before being delivered to targets. This filtering cuts down on the message traffic. In our example above, filters are very important if, in addition to Start and Stop, there were simulation-based tutorials that transmit the spatial location of every user every five seconds. In this case, the Class Participation program is interested in the Start and Stop of the simulation, but has no desire to receive the spatial updates. In this scenario, providing filtering adapters could reduce the message traffic by well over 99%.
In addition to adapters that allow the message channels to de-couple producers and consumers of messages, it is important to allow for separating in time the production and consumption of a message. Returning to our Tutorial example from above, many of the students may be performing the tutorial at night. The teacher will not connect up the Class Participation and Extra Help programs until the morning. In this case, the message channel needs to be able to save the Navigation messages that were produced the night before until the teachers programs have a chance to retrieve them.
These requirements have led us to a distributed messaging queue architecture that supports channels, managers, quality, durability, and transactions. Many of the users of these channels will utilize them through the existing event or messaging frameworks that their authoring environment gives them. For example, simulations whose navigation and other multi-player information is based on Microsofts DirectPlay interfaces will continue to do so. An IMS implementation could provide an implementation of a DirectPlay provider, moving the simulation information across message channels in a manner transparent to the author of a game.
Resolution of technical issues
The current state of the art in distributed message queue architectures is not quite up to providing all of these services. The implementation of the messaging interfaces in products is likely to be incremental. The following factors will influence the degree of interoperability provided by message channels as well as the richness of functionality that those channels can provide:
Rate of implementation of forthcoming message queue standards. The forthcoming CORBA Notification Service provides all of the features that are outlined here. However, all implementations of the CORBA Event Service, upon which the Notification Service builds, are still in their infancy.
Advancement of the capabilities of the Microsoft Message Queue Server interfaces. Currently, these interfaces do not have facilities for multi-casting messages or managing the quality attributes of messages, especially in the area of message lifecycle. On the other hand, the Message Queue Server has extensive support for offline queues, transactions, connectors to existing messaging products, and security. These capabilities should allow it to be built up to the capabilities described in the IMS Messaging interfaces fairly quickly.
Offline activity on message queues to support offline learning is an area that needs to be understood in greater detail. The computing industry is making great strides in providing easy to use messaging products which provide offline support. However, how this translates into effective information exchanges between learning resources is another matter.
Messaging Service Structure
Levels of service
Since the industry has not delivered messaging solutions that encompass the entire breadth of functionality defined by these interfaces, it is likely that organizations will implement the messaging capabilities described here in stages. In order for content authors to be able to write content today that will be upwardly compatible in the future, the IMS suggests the following levels of service:
Level 1: Unstructured messages over non-secure, non-transacted channels. This is the absolute minimum. Using these features, authors can create messages in which the message body contains an XML or any other text stream. These streams can be based on standard schemas described elsewhere in this document. Receiving programs can decode these messages by parsing the text stream and interpreting the semantics of the information. If an author requires secured communications, the message body can be encrypted with a digital certificate just as e-mail is encrypted today.
Level 2: Typed and structured messages, with the possibility of atomic and securable channels. Typed messages are actual objects, such as the Navigation message defined above. A structured message is one that has the structure, or semantics, of the message declared in the message header, rather than embedded into the body of the message. Both of these message types lend themselves to being filtered by clients without having to parse or decode the body of the message.
Level 3: Filterable message channels and publish/subscribe capabilities. Filtering allows clients to push the filtering tasks upstream onto the channel. The allows the channel to optimize the filtering process by combining common filter constraints from multiple clients into one filter. Publishing and subscribing capabilities allow message sources and message consumers to fine-tune their usage of the message channels. For example, a message source can determine if any clients subscribe to the messages that it produces. If no clients are subscribed, it can refrain from producing the event to increase performance.
Interface Summary
The following interfaces are reproductions of the Object Management Groups proposed Notification Service. The interface signatures have been harmonized with the other IMS signatures, and elements that rely on low level CORBA elements have been changed to allow implementations on multiple object systems.
InterfaceIMSNotificationPurposePrimary ClientsIQoSAdminDefines operations to manipulate quality of service properties.Clients manipulating event channelsIAdminPropertiesAdminDefines operations to manipulate administrative properties of an event channel.Clients manipulating event channelsIMSNotifyComm::INotifyPublishAllows suppliers of notifications to publish the names of the types of messages it will be supplying.Resources and Tools which emit information via messages ( i.e., handler implemented by the consumer, methods called by the supplier )INotifySubscribeAllows consumers of notifications to ask for, or subscribe, to particular types of notifications.Resources and Tools which consume information via messages ( i.e., handler implemented by the supplier, methods called by the consumer )ITxnPushConsumerDefines a push consumer that is under transactional control and supports publishing.Resources and Tools which emit information via messagesITxnPullSupplierDefines a pull supplier that is under transactional control and supports subscriptions.Resources and Tools which consume information via messages IStructuredPushConsumerDefines a push consumer that receives structured events.Resources and Tools which emit information via messagesITxnStructuredPushConsumerExtends an IStructuredPushConsumer to include transactional control.Resources and Tools which emit information via messagesIStructuredPullConsumerDefines a pull consumer that receives structured events.Resources and Tools which emit information via messagesIStructuredPullSupplierDefines a pull supplier that supports subscriptions and structured events.Resources and Tools which consume information via messagesITxnStructuredPullSupplierDefines a structured pull supplier that supports transactional controlResources and Tools which consume information via messages.IStructuredPushSupplierDefines a push supplier that supports subscriptions and structured events.Resources and Tools which consume information via messages.ISequencePushConsumerDefines a push consumer which receives sequences of structured events and supports publishingResources and Tools which emit information via messages.ITxnSequencePushConsumerDefines a sequence push consumer under transactional controlResources and Tools which emit information via messagesISequencePullConsumerDefines a pull consumer that receives sequences of structured events and supports publishing.Resources and Tools which emit information via messages.ISequencePullSupplierDefines a pull supplier which sends sequences of structured events and supports subscriptionsResources and Tools which consume information via messages.ITxnSequencePullSupplierDefines a sequence pull supplier under transactional controlResources and Tools which consume information via messages.ISequencePushSupplierDefines a push supplier which sends sequences of structured events and supports subscriptionsResources and Tools which consume information via messages.IMSNotifyChannelAdmin::IProxyConsumerAbstract definitions common to all proxy consumers, including QoS administration and filter administration.Implementations of proxy consumers, such as IStructuredPushConsumer.IProxySupplierAbstract definitions common to all proxy suppliers, including QoS administration and filter administrationImplementations of proxy suppliers such as IStructuredPushSupplier.IProxyPushConsumerSupports connections to channels by suppliers who will push untyped events onto the channel.Resources and Tools which emit information via messages.ITxnProxyPushConsumerA proxy push consumer under transactional controlResources and Tools which emit information via messages.IStructuredProxyPushConsumerSupports connections to channels by suppliers who will push structured events onto the channelResources and Tools which emit information via messages.ITxnStructuredProxyPushConsumerA structured proxy push consumer under transactional controlResources and Tools which emit information via messages.ISequenceProxyPushConsumerSupports connections to channels by suppliers who will push sequences of structured events onto the channel.Resources and Tools which emit information via messages.ITxnSequenceProxyPushConsumerA sequence proxy push consumer under transactional controlResources and Tools which emit information via messages.IProxyPullSupplierSupports connections to a channel by consumers who will pull untyped events from the channel.Resources and Tools which consume information via messages.ITxnProxyPullSupplierA proxy pull supplier under transactional controlResources and Tools which consume information via messages.IStructuredProxyPullSupplierSupports connections to a channel by consumers who will pull structured events from the channel.Resources and Tools which consume information via messages.ITxnStructuredProxyPullSupplierA structured proxy pull supplier under transactional controlResources and Tools which consume information via messages.ISequenceProxyPullSupplierSupports connections to a channel by consumers who will pull sequences of structured events from the channelResources and Tools which consume information via messages.ITxnSequenceProxyPullSupplierA sequence proxy pull supplier under transactional control.Resources and Tools which consume information via messages.IProxyPullConsumerSupports connections to a channel by suppliers who will make untyped events available for pulling.Resources and Tools which emit information via messages.IStructuredProxyPullConsumerSupports connections to a channel by suppliers who will make structured events available for pulling.Resources and Tools which emit information via messages.ISequenceProxyPullConsumerSupports connections to a channel by suppliers who will make sequences of structured events available for pulling.Resources and Tools which emit information via messages.IProxyPushSupplierSupports connections to a channel by consumers who will be pushed untyped events.Resources and Tools which consume information via messages.IStructuredProxyPushSupplierSupports connections to a channel by consumers who will be pushed structured events.Resources and Tools which consume information via messages.ISequenceProxyPushSupplierSupports connections to a channel by consumers who will be pushed sequences of structured events.Resources and Tools which consume information via messages.IConsumerAdminDefines the behavior for objects that create and manage lists of proxy supplier objects within an event channel.Resources and Tools which consume information via messages.ISupplierAdminDefines the behavior for objects that create and manage lists of proxy consumer objects within an event channel.Resources and Tools which emit information via messages.IEventChannelDefines the behaviors of a message channel.Proxy objects, message suppliers and message consumers.IEventChannelFactorySupports the creation of event channels.Message channel managers.IMSNotifyFilter::IFilterDefines behaviors for objects which encapsulate message filtersProxy objects which support filtering of messages.IMappingFilterAllows a filter to map its filter criteria to different content data than it was originally written for.Proxy objects which support filtering of messages.IFilterFactoryDefines operations for creating filter objects.Proxy object which support filtering of messages.IFilterAdminSupports controlling the behavior and characteristics of filter objectsProxy objects which support filtering of messagesIMSTypedNotifyChannelAdmin::ITypedProxyPushConsumerSupports connections to channels by suppliers who will push typed events onto the channelResources and Tools which emit information via messages.ITypedProxyPullSupplierSupports connections to channels by consumers who will pull typed events from a channelResources and Tools which consume information via messages.ITypedProxyPullConsumerSupports connections to channels by suppliers who will make typed events available to a channel.Resources and Tools which emit information via messages.ITypedProxyPushSupplierSupports connections to channels by consumers who will be pushed typed events from a channel.Resources and Tools which consume information via messages.ITypedConsumerAdminDefines the behavior for objects which create and manage lists of proxy supplier objects within an event channelResources and Tools which consume information via messages.ITypedSupplierAdminDefines the behavior for objects which create and manage lists of proxy consumer objects within an event channelResources and Tools which emit information via messages.ITypedEventChannelDefines the behaviors of a message channel capable of carrying typed messages.Proxy objects and message consumers and suppliers.ITypedEventChannelFactorySupports the creation of typed message channels.Message channel managers.Relationship
Origin of Interfaces
The following information is based entirely on the Object Management Groups specification of the Common Object Services Relationship Service. The actual IMS content model objects are modeled with derived versions of Nodes, Relationships, and Graph Traversals. The only changes that have been made, other than the addition of IMS context information, is the harmonization of interface signatures with the rest of the IMS and the possible removal of some low level CORBA dependencies.
Key Features
In coming up with a content representation model, the IMS was posed with a challenge. The IMS requirements called for arbitrary aggregation of content that is tied in with an authors ability to control such aggregation. The content that is part of an aggregation can be a mix of ActiveX, JavaBeans, HTML, and custom executables. The requirements also call for content that can have an arbitrarily complex sequence in which its parts are presented to a learner. This sequence can apply for all instances of a learning resource, instances in a particular virtual classroom, or specialized to a particular learner or small group of learners. In addition, the content and the machines serving up the content to be interacted with will be distributed across the Internet. The content model must support the creation of curriculums, or objectives, which can be disseminated as templates to IMS users to fill in with particular learning materials. The tools the IMS user has at their disposal should be able to assist the user by locating only materials that satisfy the requirements of the curriculum. Lastly, the content should be combined with powerful meta-data tagging to allow search and retrieval tools to find and then move the content into a variety of IMS based environments.
In deciding on a content aggregation and sequencing model, the IMS did not want to impose any particular implementation, instead allowing implementations to be tailored to different run-time requirements. There are equally valid IMS implementations that may involve simple aggregations of Web pages to complex aggregations created automatically by applying a curriculum template with fine-grained learning resources in a relational database. The IMS system will combine the curriculum template, the learners goals and existing skills, and the content in its repository to create a dynamic learning resource targeted at a particular User Interface medium. Our goal is to expose such aggregations and sequences to tools via open, powerful interfaces that can be mapped onto environment specific implementations.
We have chosen to start from the interfaces of the CORBA Relationship Service. These interfaces allow the following key features of IMS content to be exposed in an interoperable way
Learning information, such as curriculum objectives and learning resources, and the relationships between such information can be explicitly expressed and navigated
Relationships of arbitrary degree can be defined. This includes the complex relationships between learner goals, curriculum objectives, and learning materials.
Type and cardinality constraints can be expressed and checked. This allows the rules constraining the fulfillment of goals and objectives to be expressed to third party tools.
The relationships involved in content aggregation and sequencing can be traversed without activating the content involved. This allows third-party curriculum and lesson building tools to represent visually the entire scope of material involved without having to have the ability to activate such material locally inside the authoring tool. This support is critical for de-coupling the construction of curriculums and learning experiences from the construction of the content that makes these up.
Third party tools can create and apply the rules governing the traversal of a sequence of learning resources downstream from the original creation of the content. Thus, the exact sequence a particular student experiences can be controlled by a script created by the students teacher based on the students needs. The teacher could use any tool capable of creating a CORBA, Java, or ActiveX object supporting these interfaces. Such tools range from general tools like Visual Basic and Java Studio to specialized course creation tools which have a highly visual interface built around the objects of an IMS system.
The following information is reproduced from the Object Management Groups specification of the Common Object Services Relationship Service. The end of this section contains the actual IMS content model objects, which are derived versions of Nodes, Relationships, and Graph Traversals.
Distributed objects are frequently used to model entities in the real world. As such, distributed objects do not exist in isolation. They are related to other objects. Consider some examples of real world entities and relationships:
A person owns cars; a car is owned by one or more persons.
A company employs one or more persons; a person is employed by one or more companies.
A document contains figures; a figure is contained in a document.
A document references a book; a book is referenced by one or more documents.
A person checks out books from libraries. A library checks out books to people. A book is checked out by a person from a library.
These examples demonstrate several relationships:
Ownership relationships between people and cars
Employment relationships between companies and people
Containment relationships between documents and figures
Reference relationships between books and documents
Check out relationships between people, books and libraries.
Such relationships can be characterized along a number of dimensions:
Type
Related entities and the relationships themselves are typed. In the examples, employment is an relationship defined between people and companies. The type of the relationship constrains the types of entities in the relationship; a company cannot employ a monkey since a monkey is not a person. Furthermore, employment is distinct from other relationships between people and companies.
The roles of entities in relationships
A relationship is defined by a set of roles that entities have. In an employment relationship, a company plays an employer role and a person plays an employee role.
A single entity can have different roles in distinct relationships. Notice that a person can play the owner role in an ownership relationship and the employee role in an employment relationship.
Degree
Degree refers to the number of required roles in a relationship. The check out relationship is a ternary relationship; it has three roles: the borrower role, the lender role and the material role. A person plays the borrower role, a library plays the lender role and a book plays the material role. Ownership, employment, containment and reference, on the other hand, are of degree 2, or binary relationships.
Cardinality
For each role in a relationship type, the maximum cardinality specifies the maximum number of relationships that may involve that role. The containment relationship is a many-to-one relationship; a document contains many figures; a figure is contained in exactly one document. A many-to-many relationship is between two sets of entities. The ownership example is a many-to-many relationship; a person can own multiple cars; a car can have multiple owners. The check out relationship is a many-to-one-to-many relationship. A person can check out many books from many libraries. One person from one library checks out a book and a library can loan many books to many people.
Relationship Semantics
Relationships often have relationship-specific semantics; that is they define operations and attributes. For example, job title is an attribute of the employment relationship, while it is not an attribute of an ownership relationship. Similarly, due date is an attribute of the check out relationship.
Key Features of the Relationship Service
The Relationship Service allows entities and relationships to be explicitly represented. Entities are represented as CORBA objects. The service defines two new kinds of objects: relationships and roles. A role represents a CORBA object in an relationship. Passing a set of roles to a relationship factory creates a relationship.
Relationships of arbitrary degree can be defined.
Type and cardinality constraints can be expressed and checked. Exceptions are raised when cardinality and type constraints are violated. The Relationship Service does not define a new type system. Instead, the IDL type system is used to represent relationship and role types. This allows the service to leverage CORBA solutions for type federation.
The Relationship interface can be extended to add relationship specific attributes and operations. Similarly, the Role interface can be extended to add role specific attributes and operations.
The Relationship Service defines three levels of service: base, graph, and specific.
The base level defines relationships and roles.
when objects are related, they form graphs of related objects. The graph level extends the base level service with nodes and traversal objects. Traversal objects iterate through the edges of a graph. Traversals are useful in implementing compound operations on graphs, among other things.
the third level defines specific relationships.
A conforming Relationship Service implementation must implement level 1 or levels 1 and 2 or levels 1, 2 and 3.
The Relationship Service requires a notion of object identify. As such, it defines a simple, efficient mechanism for supporting object identity in a heterogeneous, CORBA-based environment. We believe the mechanism to be of general utility for other services.
Distributed implementations of the Relationship Service can have navigation performance and availability similar to CORBA object references; role objects can be collocated with their objects and need not depend on a centralized repository of relationship information. As such, navigating a relationship can be a local operation.
The Relationship Service allows so-called immutable objects to be related. There are no required interfaces that objects being related must support. As such, objects whose state and implementation were defined prior to the definition of the Relationship Service can be related objects.
The Relationship Service allows graphs of related objects to be traversed without activating related objects.
The Relationship Service is extensible. Programmers can define additional relationships.
The Relationship Service vs. CORBA Object References
(IMS NOTE: Both JavaBeans and ActiveX Documents and Controls use an embedded object reference model for depicting containment relationships. This discussion is roughly applicable to those environments as well. The IMS is investigating how the Relationship Service compares to the W3C Resource Description Format (RDF) model for depicting relationship semantics in a sufficiently powerful way.)
CORBA: Common Object Request Broker Architecture and Specification defines object references that clients use to issue requests on objects. Object references can be stored persistently. When is it appropriate to use object references and when is it appropriate to use the Relationship Service? The Relationship Service is appropriate to use when an application needs any of the following capabilities that are not available with CORBA object references:
Relationships that Are Multidirectional
When objects are related using the Relationship Service, the relationship can be navigated from any role to any other role. The service maintains the relationship between related objects. CORBA object references, on the other hand, are unidirectional. Objects that posses CORBA object references to each other can only do so in an ad hoc fashion; there is no way to maintain and manipulate the relationship between the objects.
Relationships that Allow Third Party Manipulation
Since roles and relationships are themselves CORBA objects, they can be exported to third parties. This allows third parties to manipulate the relationship. For example a third party could create, destroy or navigate the relationship. Third parties cannot manipulate object references.
Traversals that Are Supported for Graphs of Related Objects
When objects are related using the Relationship Service, they form graphs of related objects. Interfaces are defined by the Relationship Service to support traversing the graph.
Relationships and Roles that Can Be Extended with Attributes and Behavior
Relationships have relationship-specific semantics. For example, the employment relationship has a job title attribute. Since relationships and roles are objects with well-defined OMG IDL interfaces, they can be extended through OMG IDL inheritance to add such relationship-specific attributes and operations.
Resolution of Technical Issues
Modeling and Relationship Semantics
An application designer models a problem as a set of objects and the relationships between those objects. Using OMG IDL, the application designer directly represents the objects of the model. Using the Relationship Service, the application designer directly represents the roles and relationships of the model. The Relationship and Role interfaces can be extended using OMG IDL inheritance to add relationship and role specific attributes and operations. For example, a designer might define the employment relationship to have an operation returning a job title.
Managing Relationships
The IRelationshipFactory interface defines an operation to create a relationship, given a set of roles. The Role and Relationship interfaces define operations to delete and navigate relationships between objects.
Constraining Relationships
Type, cardinality and degree constraints on relationships are expressed in the interfaces. The IRoleFactory::CreateRole operation can raise a RelatedObjectTypeError exception. This allows implementations of the Role interface to place further constraints on the type of the related objects. For example, an EmployedByRole can ensure related objects are people. An attempt to have it represent a monkey would raise a RelatedObjectTypeError exception.
Similarly, the IRelationshipFactory::Create operation can raise a RoleTypeError exception. This allows implementations of the Relationship interface to put constraints on the type of the roles. For example an Employment relationship can ensure there is an EmployerRole and an EmployeeRole.
The IRelationshipFactory::Create operation can also raise a DegreeError exception. This ensures that there are the correct number of roles.
The role objects themselves enforce maximum cardinality constraints. A role can raise a MaxCardinalityExceeded exception and refuse to participate in a relationship if its maximum cardinality would be exceeded. Roles define an operation to ask if their minimum cardinality constraint is being met.
Referential Integrity
If the Relationship Service is used in an environment supporting transactions, strict referential integrity is achieved. That is, if an related object refers to another (via a relationship), then the other related object will also refer to it. Without transactions, strict referential integrity cannot be achieved since a failure during execution of the relationship construction protocol could cause a dangling reference.
Relationships and Roles as First Class Objects
Our design defines both relationships and roles as first class objects. This is extremely important because it encapsulates and abstracts the state to represent the relationship, allows third party manipulation of the relationship and allows the roles and relationships themselves to support operations and attributes.
Different Models for Navigating and Constructing Relationships
The Relationship Service defines interfaces for constructing and navigating relationships component-by-component. These building block operations can be used by a higher-level service, such as a query service.
Efficiency Considerations
Our design has several features that allow for highly optimized implementations. Performance optimizations are achieved by clustering and/or caching of connection information.
Clients can cluster related objects and their roles by their selection of factories. Our design defines the containment relationship logically. It does not imply physical clustering of state or execution, However, it serves as a good hint to implementations for clustering. An environment can choose to cluster containers and contained objects. The GetOtherRelatedObject operation can be implemented to cache remote related objects. The cached information is immutable; once a relationship is established, the roles and related objects will not change.
Use of Object References for Managing Groups
Currently, the IMS specification provides that the hierarchy of Groups within an IMS management system is maintained via object references to a Groups parent Group and its child Groups. There is no theoretical reason why the Group structure of an IMS cannot be modeled with relationships as the content structure is here. The IMS will revisit this issue during the comment period of the specifications.
Implementation Scenarios
Aggregating Materials
An IMS Resource Object extends a node in a Relationship Graph (not to be confused with nodes in an XML document ). By virtue of being a node in such a graph it can participate in many roles with other Resource objects. It can, for example, contain other resources, refer to other resources or be contained by or referenced by other resources. In the following example we see an IMS Resource named Frog Dissection that aggregates two other resources, a Lesson and a Test. The Lesson Resource in turn contains the Intro Resource, and it refers to the Lab Resource. Note that Resources can support many roles at the same time. The Lesson resource in this example supports a ContainedInRole ( it is contained in the Frog Dissection Resource), a ContainsRole (it contains the Intro), and a ReferencesRole ( it refers to the Lab resource).
The Containment and Relationship roles are the primary relationship types used to satisfy the aggregation requirements for IMS content.
Let's walk through the steps of creating the Frog Dissection Resource (FDR). We will assume that this resource is aggregating two already existing resources, the Lesson and the Test which have associated roles C and F already defined (see diagram). Examining the graph above, we see that the FDR node supports two roles, a ContainsRole(A) and a ReferencesRole (D). We will illustrate the creation of the FDR node and these two roles using the following pseudo-code.
fdr = new Resource("Frog Dissection"); // create the root node
A = fdr.addRole(ContainsRole);
D = fdr.addRole(ReferencesRole);
Then we create the Containment and Reference relationships and create links to the Lesson and Test Resources.
B = IMSRelationship.create(ContainmentType);
E = IMSRelationship.create(ReferenceType);
B.addroles(A, C);
E.addroles(D, F);
Higher Level Learning Objects and Objectives
The Relationship graph is capable of representing all levels of learning objects and any learning or performance objectives that may be associated with them. The diagram below illustrates how a Biology curriculum might be related to a set of courses.
Disaggregating and Repurposing Materials
Resources which are represented as Nodes in a Relationship graph are easily repurposed by performing aggregation and disaggregation manipulations on the graph itself without having to alter the content of the material itself in any way. Let's imagine that the Test used by the Frog Dissection Resource is, in fact, a test over standard dissection practices that could be used by any resource wishing to assess learners on these skills. The fact that the Test supports a ReferencedByRole means that it might also be referenced by any number of other resources. In the graph below we show two resources sharing the same dissection test.
Creating a Sequence through Content
For the Frog Dissection Resource described in the previous section we may wish to control the sequence in which the aggregate parts are visited by a learner, that is, we might wish to insure that the INTRO and LAB are completed before the TEST is taken. Sequence control is managed through the use of the IMS Traversal Interface. This interface is used to traverse graphs of related resource objects according to some traversal criteria which functions as a programmable iterator to determine which node is "next" to be visited from a given node.
There are several built in traversal criteria that can be used for simple cases of tree structured containment such as exist in our example. In our case we can insure that the Resources INTRO, LAB and TEST appear in the correct sequence by using the supplied Depth First Traversal criteria. In more complex cases of aggregated Resources developers will use tools to customize and edit the traversal criteria according to previous performance and information culled from a student's profile and personal preferences.
Relationship Service Structure
This section provides information about the levels of service; the specification is organized around these levels. It also describes the hierarchy of Relationship Service interfaces and explains the main purpose of each interface.
Levels of Service
The Relationship Service defines three levels of service: base relationships, graphs of related objects, and specific relationships. The specification is organized around these levels.
Level One: Base Relationships
The Relationship and Role interfaces define the base Relationship Service. Figure 9-1 illustrates two instances of the containment relationship. The document plays the container role; the figure and the logo play the containee role. The diamond is an object supporting the IRelationship interface. The small circles are objects supporting the IRole interface.
Figure 9-1 Base relationships.
Roles represent objects in relationships. Roles have a maximum cardinality. As illustrated, the container role can be involved in many instances of a relationship. The containee roles can only be involved in a single instance of a relationship.
Figure 9-2 illustrates the navigation functionality of relationships; for example the arrow between a role and another role indicates it is possible to navigate from one role to another. The arrow does not, however, indicate that the object reference to the other role is necessarily stored by the role.
Figure 9-2 Navigation functionality of base relationships.
Table 9-1 lists the interfaces to support relationships and roles.
Level Two: Graphs of Related Objects
Distributed objects do not exist in isolation. They are connected together. Objects connected together form graphs of related objects. The Relationship Service defines the ITraversal interface. The ITraversal interface defines an operation to traverse a graph. The traversal object cooperates with extended roles supporting the IMSGraphs::IRole interface and objects supporting the INode interface.
Figure 9-3 illustrates a graph of related objects. The folder, the figure, the logo and the book all support the INode interface. The small circles are roles supporting the IMSGraphs::IRole interface..
PUT IN FIGURE 9-3 GRAPHS
Table 9-3 lists the interfaces to support graphs of related objects.
Level Three: Specific Relationships
Containment and reference are two important relationships. The Relationship Service defines these two binary relationships. Table 9-4 and Table 9-5 list the interfaces defining specific relationships.
Hierarchy of Relationship Interface
The relationship interfaces are arranged into the interface hierarchy illustrated in Figure 9-4.
Hierarchy of Role Interface
The role interfaces are arranged into the interface hierarchy illustrated in Figure 9-5.
PUT IN FIGURE 9-5 ROLE INTERFACE HIERARCHY
The IRole interface defines operations to efficiently navigate relationships between related objects.
The IMSGraphs::IRole interface defines an operation to return the edges that involve the role. This is used by the traversal service defined at the graph level.
Finally, IContainsRole, IContainedInRole, IReferencesRole and IReferencedByRole are specific roles for two important relationships: containment and reference.
The IMS is deriving from Node an interface called IResource. This interface adds an object reference for the IGroup that a resource exists within and an object reference for the ISession under which the IResource and its related objects are running. In addition, we are creating relationships to cover aggregation by embedding and aggregation by reference as well as a relationship to cover sequencing.
Interface Summary
The Relationship Service defines interfaces to support the functionality described in section 9.2. Table 9-1 through Table 9-5 give high level descriptions of the Relationship Service interfaces.
Table 9-1 Interfaces defined in the IMSObjectIdentity module
InterfacePurposePrimary ClientsIMSObjectIdentity::
IIndentifiableObjectTo determine if two objects are identicalThere are many clients. The graph level of the Relationship service is one.
Table 9-2 Interfaces defined in the IMSRelationships module
InterfacePurposePrimary ClientsIMSRelationships::
IRelationshipRepresents an instance of a relationship typeClients that navigate between related objects.IRelationshipFactorySupports the creation of relationshipsClients establishing relationshipsRoleDefines navigation operations for relationships. Implements type and cardinality constraints.Clients that navigate between related objects.
Relationship factories.IRoleFactorySupports the creation of roles.Objects participating in relationship.IRelationshipIteratorIterates the relationships in which a particular role object participates.Clients that navigate relationships.
Table 9-3 Interfaces defined in the IMSGraphs module
InterfacePurposePrimary ClientsIMSGraphs::
ITraversalDefines an operation to traverse a graph, given a starting node and traversal criteriaClients that want a standard service to traverse graphsITraversalFactorySupports the creation of a traversal objectClients that want a standard service to traverse graphs.ITraversalCriteriaProvides navigation behavior between nodes.Traversal ImplementationsIRoleExtends the IMSRelationships::IRole interface to return edgesClients that traverse graphs of related objectsIEdgeIteratorReturns additional edges from a role.Clients that traverse graphs of related objectsINodeFactorySupports the creation of nodes.Clients that create nodes in graphs
Table 9-4 Interfaces defined in the IMSContainment module
InterfacePurposePrimary ClientsIMSContainment::
RelationshipOne-to-many relationshipClients that depend on containment relationship typeIContainsRoleRepresents an object that contains other objectsClients that navigate containment relationships between objectsIContainedInRoleRepresents an object that it contained in other objectsClients that navigate containment relationships between objects.
Table 9-5 Interfaces defined in the IMSReference module
InterfacePurposePrimary ClientsIMSReference::
RelationshipMany-to-many relationshipClients that depend on the reference relationship type.IReferencesRoleRepresents an object that references other objectsClients that navigate reference relationships between objectsIReferencedByRoleRepresents an object that is referenced by other objectsClients that navigate reference relationships between objects
InterfaceIMSObjectIdentity::PurposePrimary ClientsIIdentifiableObjectTo determine if two objects are identicalThere are many clients. The graph level of the Relationship Service is one.InterfaceIMSRelationships::RelationshipRepresents an instance of a relationship type.Clients that navigate between related objects.IRelationshipFactorySupports the creation of relationships.Clients establishing relationships.IRoleDefines navigation operations for relationships. Implements type and cardinality constraints.Clients that navigate between related objects. Relationship factories.IRoleFactorySupports the creation of roles.Objects participating in relationships.IRelationshipIteratorIterates the relationships in which a particular role object participatesClients that navigate relationships.InterfaceIMSGraphs::TraversalDefines an operation to traverse a graph, given a starting node and traversal criteria.Clients that want a standard service to traverse graphs.ITraversalFactorySupports the creation of a traversal object.Clients that want a standard service to traverse graphs.RoleExtends the IMSRelationships::IRole interface to return edges.Clients that traverse graphs of related objects.IEdgeIteratorReturns additional edges from a role.Clients that traverse graphs of related objects.NodeDefines operations for a related object to reveal its roles.Clients that traverse graphs of related objects.INodeFactorySupports the creation of nodes.Clients that create nodes in graphs.ResourceExtends the INode interface. Defines operations that allow a learning resource to navigate into relationships as well as the rest of its IMS environment.Clients and IMS learning resources which wish to access the IGroup and ISession objects in which the learning resource is running.InterfaceIMSContainment::RelationshipOne-to-many relationshipClients that depend on the Containment relationship type.IContainsRoleRepresents an object that contains other objects.Clients that navigate containment relationships between objects.IContainedInRoleRepresents an object that is contained in other objects.Clients that navigate containment relationships between objects.InterfaceIMSReference::RelationshipMany-to-many relationshipClients that depend on the reference relationship type.IReferencesRoleRepresents an object that references other objects.Clients that navigate reference relationships between objects.IReferencedByRoleRepresents an object that is referenced by other objects.Clients that navigate reference relationships between objects.Property
Origin of Interfaces
The following information is based entirely on World Wide Web Consortiums ( W3C ) Document Object Model. The only changes that have been made, other than the addition of IMS context information, is the harmonization of interface signatures with the rest of the IMS and the possible removal of some low level W3C dependencies.
Property Service Description
Key Features
The IMS requirements call for managing a great deal of information. Much of this information is quite structured and is fit to be managed by objects, such as Groups, Message Channels, Security, and so forth. There is a good amount, however, that is quite dynamic, varies from instance to instance, and does not necessarily impact the fundamental type of an object. For example, two message channels in which one supports filtering and one does not are two distinct types of Message Channels. There are different, or at least additional, methods on the objects that are necessary for using them properly. However, two User objects, one which supports a simple address and e-mail and the other which supports multiple e-mails, notification preferences, and a preferred learning style are not so clearly different types of objects. It could be argued that the additional information carried by the second profile should be added via a new interface and defined with IDL. This will work. However, much of the usage and manipulation of this information is up to the program which reads it, and it is likely that highly stylized programs might want to add even more information to the profile of their own choosing.
In addition to these types of questions, the IMS needed to create interfaces for manipulating meta-data. Meta-data by definition is of unconstrained complexity. Simple meta-data is basic attribute/value pairs. However, the meta-data tagging enabled by the Resource Description Format (RDF) can be quite complex, indeed. In fact, the RDF may be able to rival the proposed Relationship Service in its expressive power. In the end, though, both the simple attribute/value pair meta-data and the RDF meta-data are instances of a Meta-data object as far as the IMS is concerned.
The IMS Property Service allows for arbitrarily complex dynamic property sets to be added to a resource, and it allows for arbitrarily complex meta-data to be associated with a resource. The IMS does not stipulate the distinction between attributes that should be defined using the typing system of a target object environment and those that are defined using this interface. Nor does it stipulate the ultimate distinction between meta-data and operation data on objects themselves.
Property Service Vs other options
Both CORBA and COM provide facilities for associating dynamic information with an object, which does not change its fundamental type. The CORBA service in particular is being augmented to include tagged information instead of just attribute/value pairs. The basic GetProperty, SetProperty, and AddProperty methods of IProperty would likely be implemented by these facilities. However, the expressive power of XML and RDF are envisioned by the IMS as the method of choice for conveying dynamic information about objects.
The IMS has purposely chosen to promote the use of XML schemas for conveying information that would normally be put in IDL, such as user profile information like learning style, existing skill set, etc. We do so since this type of information is very ill defined in todays marketplace. IMS will suggest a basic set of schemas. However, much of the activity over the next few years by vendors will flesh out what these definitions should be. At that point, it is expected that the IMS will help the industry standardize on XML schemas for the effective interchange of this information.
Resolution of Technical Issues
Currently, there are no RDF parsers on the market, and the W3C has yet to complete the RDF object model. Therefore, all of the current interfaces proposed are directly in XML. The base sets of meta-data are also expressed in XML. The IMS does not suggest extending the base IMS meta-data sets until this work is completed. When RDF is completed, the IMS will provide conversion for meta-data objects using the base sets. Any extended meta-data structures will have to be converted by vendors on their own.
Property Service Structure
Levels of service
Interface Summary
InterfaceIMSProperty::PurposePrimary ClientsIPropertyProvides for manipulate of arbitrarily complex dynamic property sets, including meta-dataMeta-data tools and learning resources that wish to specialize their appearance or functionality based on user profile information.The rest of the Document Object Model interfaces are not summarized here.Security
Origin of Interfaces
The following information is based entirely on National Institute of Standards and Technologys Role Based Access Control model. The only changes that have been made, other than the addition of IMS context information, is the harmonization of interface signatures with the rest of the IMS and the possible removal of some low level NIST dependencies.
Note on the status of RBAC certification. The Common Criteria for Information Technology Security Evaluation (CC) defines the basis for evaluation of security properties of Information Technology produces and systems. The CC is progressing toward international standardization under the auspices of ISO/IEC, JTC 1, SC27/WG3. A CC Protection Profile for RBAC is being developed. Conformance evaluation and testing of the RBAC Security Service will be available in the future using the CC RBAC Protection Profile.
Security Service Description
Key Features
The IMS Security Service Interfaces provides authentication, access control, integrity, and confidentiality services to IMS Applications. Authentication provides a users identity to an application. Access control enforces access policy on objects given a users identity, user attributes, and object attributes. Integrity ensures tamper-proof communication. Confidentiality ensures private communication. The Security Service interfaces are designed so that they may be implemented within the commonly available security environments, such as, CORBA and COM.
Authentication mechanisms often differ between security environments. IMS Applications and Objects rely on authentication information provided by means of the Security Service Interfaces. Using the Security Service Interfaces, an IMS Application or Object is able to:
Obtain the principal that it represents, i.e., in the name of whom, what organization, or what system process does the IMS Object perform operations.
Obtain the principal of the application or object requesting its services.
The IMS security service uses the Role Based Access Control (RBAC) Model designed by NIST. Access control to IMS Objects using the NIST RBAC mechanism is provided by the security environment and by the IMS Object. RBAC is not the only means by which IMS Objects are protected from unauthorized access. Depending on the access policy for an IMS Object, the Object can enforce access control beyond the basic RBAC mechanism by means of attributes other than roles, e.g., enrollment in a specific class. Some of these additional attributes are made available to an IMS Object through the Profile Service. Using the Security and Profile Service Interfaces, an IMS Application or Object is able to:
Obtain the attributes of the principal that it represents.
Obtain the attributes of the principal of the application or object requesting its services.
Obtain its attributes.
With sufficient privilege, administer access control policy by managing user/role, role/role, and role/operation relationships.
Using the Security Service Interfaces, an IMS Application or Object is able to make authenticated requests to IMS Objects. Requests may have integrity and/or confidentiality protection. When secure requests are made, the responses are equally secure.
Security Service Vs other options
There are many security environments in common use. Each security environment may have different mechanisms and algorithms supporting the security services for authentication, access control, integrity, and confidentiality. Each security environment may have different interfaces to those services, interfaces that are high level and/or low level. For example, CORBA and COM support different security environments. The interfaces to their security services are different. Although a CORBA specification exists for interoperability between CORBA and COM objects, the CORBA specification does not include interoperability of security services.
The IMS Specification includes high level interfaces to security services in order to enhance the portability and interoperability of IMS Applications and Objects between different security environments. By using the IMS Security Service Interfaces, IMS Applications and Objects have the opportunity to securely communicate between IMS Systems. The IMS Security Service Interfaces are designed so that they may be implemented within existing security environments using the interfaces of the host environment.
In order to provide a common metaphor for managing access control across different IMS Systems, the IMS Specification includes interfaces to the Role Based Access Control (RBAC) Model developed by NIST. The RBAC metaphor is natural to the way administrators think of an individuals relationship to an organization, i.e., in terms of the job position or roles that an individual has within the organization. With RBAC, administrators do not have to translate the way they think about individuals responsibilities into an access control mechanism. With RBAC, the natural way of thinking about an organization is the access control mechanism. As a result, RBAC lowers the cost of administration and makes the process of administrating access control policy less error-prone as compared to other access control mechanisms, in particular, associating users directly with permissions. The NIST RBAC Model supports non-trivial access control policies while allowing efficient implementation.
Resolution of technical issues
The Security Services Interfaces provide the opportunity for portability and interoperability of security services between IMS Systems. The Security Services Interfaces of IMS Systems may be implemented using a variety of mechanisms and algorithms available within the security environment hosting the implementations. The extent to which IMS Applications and Objects securely interoperate between IMS Systems is determined by the IMS System implementations.
Providing a single authentication mechanism between IMS Systems is a particularly difficult issue. It requires consensus among implementers as to which authentication mechanism(s) to support. Organizations that require the capability of interoperating with IMS Systems of other organizations may have trust credentials issued by other organizations.
The use of Public Key Infrastructure (PKI) as a means of authentication between security environments is increasingly supported and can serve as a means of authentication across IMS Systems implemented in different security environments. Public key certificates as a means of authentication can currently be used in many environments, e.g., HTTP, email, CORBA, COM, and Kerberos. Public key certificates are the only widely supported authentication and integrity mechanism for messaging systems such as email. In order to use public key certificates, an organization must invest in the necessary infrastructure. While the technology to support this infrastructure is available, there are serious organizational and legal policy questions that must be decided by an organization before using the technology.
Security Service Structure
Levels of service
RBAC0
RBAC 0 is the most basic type of role based access control service. It defines the functionality to define users and roles without the use of inheritance or separation of duty. These basic services are built on by the other classes of RBAC service.
RBAC1
RBAC 1 takes RBAC 0 and adds the notion of inheritance relationships between roles
RBAC2
RBAC 2 takes RBAC 0 and adds the notion of separation of duty. Separation of duty establishes mutual exclusion between roles on two levels. Static separation of duty controls how roles are assigned to users. A user cannot be assigned two roles that are labeled statically separate. Dynamic separation of duty controls how the active role set is formed for the user. Two roles with dynamic separation cannot both end up in the active role set.
RBAC3
RBAC 3 takes RBAC 0 and includes both inheritance and separation of duty.
Interface Summary
InterfaceIMSRBAC::PurposePrimary ClientsIActiveRoleSetExpose those roles assigned to a user which are in effect for a particular context.Access Control List evaluation programs and security administration clients.IAssignedRoleSetThe set of roles directly assigned to the user.Security administration clients.IAuthorizedRoleSetThe set of roles associated with the user, including inherited roles.Security administration clients.IInheritMaps a role to the set of roles from which it inherits.Security administration clients.IOperationDefines a method and the objects on which that method can be invoked. This is the smallest securable unit.Access Control List evaluation programs and security administration clients.IOperationDBDefines the collection of operations in an RBAC system.Security administration clients.IRBAC0Defines the most basic behaviors of an RBAC system.Security administration clients.IRBAC1Adds the notion of inheritance of roles to RBAC0Security administration clients.IRBAC2Adds the notion of separation of duty to RBAC0Security administration clients.IRBAC3Combines RBAC0, RBAC1, and RBAC2Security administration clients.IRoleDefines a logical group that shares common duties. The interface supports cardinality constraints.Security administration clients, notification type messages ( for generic targeting of messages )IRoleDBThe collection of roles for an RBAC system.Security administration clientsIRoleUserDBThe collection of mappings between users and the roles that they are assigned.Security administration clients.ISecurityDefines operations that allow access to a security principal and to perform private method invocations ( i.e., encrypted invocations ).Resources and Tools that require secure communications or explicit authorization.ISeparationOfDutyDefines the mapping between a role and the roles it conflicts with.Security administration clients.ISubjectLabels a users security session.Access control list evaluation programs and security administration clients.IUserDefines a user within the security system. This interface will be combined with the IMSGroup::IUser interface.Access control list evaluation programs and security administration clients.Persistence
The IMS faces a difficult challenge when it comes to persistence. The industry has many, sometimes competing, standards around which persistence of data and objects is performed. For traditional components, such as JavaBeans and ActiveX controls, and compound documents, such as Microsoft Office documents, a form of serialization is used. Many existing legacy applications, as well as data driven web pages, use either variants of ODBC or JDBC. Modern object systems or object/relational systems use standards from the Object Database Management Group to provide interoperability. Lastly, the coming adoption of XML as the data lingua franca has many companies looking at XML based serialization formats. In this atmosphere, the IMS is faced with a few requirements that seem to call for a standardized persistence model.
First and foremost is the ability for a student to pause their work and resume it at a later time, potentially from a different workstation. In addition, there is a requirement to easily transfer learning resources, simple and complex, from one IMS environment to another. Since an IMS learning resource can be a complex graph of objects, moving it is no mean feat. The IMS in general attempts to decoupage the interface to the various components of a learning system from the actual implementations of those components. However, when it comes to allowing an interoperable transfer mechanism, as in the later case, or a user state bucket, as in the former, we are in danger of forcing implementations into a narrow line.
Since the industry as a whole has not come up with one common way for persisting objects that works in all cases, the IMS is hoping to use a form of XML serialization to enable the persistence features required in an IMS system. However, the IMS is about transferring objects, not just data. XML currently only deals with data, though there are a host of options on the horizon for moving objects along with their data via XML. Microsoft, members of the ODMG, and many others are working on this problem. The IMS hopes to work with the industry to adopt a common XML object serialization format that will allow the movement of learning resources between IMS implementations. The IMS will not dictate any particular persistence mechanism once the learning resources are instantiated inside of an IMS implementation.
Digital Commerce
Commerce Service Description
Key Features
Commerce Service Vs other options
Resolution of technical issues
Commerce Service Structure
Levels of service
Interface Summary
Proof of Concept Implementation
Introduction
Scope and Status of Prototype
The prototype consists of a Management System, Content Server and Profile Server which are intended to demonstrate key areas of the IMS Specifications and to test the viability of the central concepts of the IMS design philosophy. The prototype was created as a proof-of-concept implementation and as a platform for further experimentation and design refinement.. As a proof-of-concept work the prototype concentrates on those features of the IMS instructional model which set it apart from existing online instructional platforms. Features commonly found on existing platforms which did not illustrate core requirements or did not require innovative approaches were given minimal representation or omitted altogether. The prototype purposely does not address issues of performance, scalability and ease of use that will be important in the development of any robust and large scale commercial implementation
Platform requirements
The prototype has been developed using Java and CORBA technologies. To access all the current prototype features client browsers must support JDK 1.1.5 and RMI which is used to interface applets with CORBA objects running on the server. HTTP communications are handled by servlets running in conjunction with the Java Web Server. The prototype is currently running on an NT Server 4 with 128 MB RAM and uses approximately 100 MB disk space. The ORB used for development was Visigenic's Visibroker.
User Interface
Logging In
Entry to the prototype is through a log in screen which collects the user's name and password and posts them to a LogIn servlet. The servlet finds or creates an appropriate User object and stores it with the user's Session which leverages the Java Web Server's built in session object. The user's start group is looked up and an initial page is generated containing information about the user's current group and its associated resources, members and tools. A Management Bar appearing on the left side of the main display screen references Groups, Resources, Members, Communications, Backpack, and Control Panels.
Groups
The group is the organizing construct in the design of the prototype. A group includes members, resources, tools and subgroups. It has its own dedicated chat and notification channels. Resources and utilities dynamically configure their presentation to the user based in part on group data. From the Management Bar members, resources, tools and subgroups can be added or edited.
Resources
Resources may be added, accessed and edited from the Management Bar. A resource in the IMS system is represented by a Resource Object which contains a reference to the resource's location, the groups it belongs to, its sign posts which govern user notifications and other administrative data. Enabling or disabling a resource's notification events is done through the Management Bar's Control Panel.
Members
A group member has access to all of a group's resources, tools, other members and selected subgroups. From the Management Bar a user can search for other members, list current members or see who is presently on line.
Communications
Various communication tools are available to group members from the Management Bar. These include a threaded Discussion List, Message Service, and Chat. These utilities differ from common implementations of these services found on standard online educational platforms in that they leverage information from their user's profile and group membership to create dynamic presentations tailored to the individual user. The Message Service and Chat make heavy use of CORBA services proxied by the Message Channel Manager RMI interface.
Backpack
Selecting the Backpack option from the Management Bar displays references to programs and tools that users would use to personalize their experience. A user may add his or her favorite tools, such as a Calculator or a Statistics Tool, and carry these tools across different groups.
Control Panel
The Control panel enables the user to edit and control all other Management Bar items.
Overview of Prototype Architecture
Management
Users are represented by a User object that contains pointers to user profiles, preferences, records, group membership and management data. The management of users, groups, and resources is handled by the central administrative object called the Coordinator.
Messaging
Support for event notification, asynchronous messaging, and interoperability between applications at the data exchange level is made possible by a Channel Manager which leverages the Corba Event services. The Channel Manager allows applications to access or create CORBA event channels for asynchronous messaging and provides methods for sending messages, waiting for messages, or listing existing channels. Each group has a dedicated chat and notification channel and applications may create their own channels for handling multiuser synchronous collaboration. Applets in browsers may have full access to these functions through an RMI server interface. Web pages can send messages by posting data to a server CGI_MessageRouter servlet as demonstrated in the tutorial concluding this section.
Messages may be simple or structured. Simple messages may consist of any string, serialized object, or byte array of data. Structured messages employ the Message object to attach type information to the message to assist receiving applications in interpreting the message body.
The message channel subsystem can be used to route messages to various channels, users or files. Messages sent to a dedicated router channel are intercepted by the Message Router, a stand alone RMI utility whose only function is to listen for messages and route them to their correct destinations. The router checks the message for certain routing information that tells it where the message is to be forwarded. If the routing information indicates that the message is to be sent to a given user the router looks up the user's notification preferences in the user's profile and makes a best effort attempt at delivery. The most common notification preference will probably be an email address, but might be another named channel or file name where the message is to be stored.
In the following diagram we see how messages can flow across the system. In this illustration a student takes a test presented in a browser window. The test data is sent to a grading application for scoring and the results are sent to the instructor via email, the instructor's preferred notification method.
1. Answers are Posted to the CGI_MessageRouter on the server.
2. The Router forwards the answers to the Test Data channel.
3. A grader application monitoring the channel grades the answers.
4. The assessment data is sent to the Message Router.
5. The Message Router finds the instructor's notification preferences.
6. The Message Router emails the assessment to the instructor.
Content
Content is represented by a Resource object which includes information on where the application program is located and methods for setting and getting notification sign posts, and other management data. An application will naturally contain points at which it makes sense to publish event notifications about a user's progress. At such points in the program an appropriate signpost is consulted. The signpost indicates whether the owner or administrator of the resource has elected to enable or disable the resource and where the notification message is to be sent. The tutorial which concludes this section demonstrates the structure of signposts and how they can be created and used in conjunction with the Resource Agent utility class.
Content Server
The IMS Content Server is primarily intended to showcase both the use of meta-data for finding learning resources on the World Wide Web and the creation of meta-data for making learning resources easier to find. The Content Server is a proof-of-concept implementation and not a full blown repository of learning resources. It was created to demonstrate the efficacy of meta-data for accessing learning resources and is intended to support:
Effective discovery via the Internet of high quality materials for a particular educational or training purpose.
Management of materials, including intellectual property rights, commerce, and customization of learning experiences.
Reuse of educational resources at micro and macro levels.
(See http://www.imsproject.org/meta-data)
In the current version of the server, you can create and edit meta-data for learning resources. You may also elect to have this meta-data rendered in xml/rdf format for inclusion in a web page or associated meta-data file. There are several fields that may be filled out in order to create the meta-data for a learning resource. Here is a partial listing of these fields
location
version number
format
title
author
keywords
language
subject
abstract
learning level
educational objectives
use time
source
prerequisites
relation
steward
use rights
price code
catalog id
Profile Server
The IMS Profile Server is an independent server accessed by the Management System to create, store, edit and retrieve user profiles and records. In the current version of the prototype the interface from the Management System to the Profile Server is not actively implemented but for testing purposes calls to the Profile Server may be made using a straightforward telnet protocol as outlined in the installation instructions. The IMS Profile Server supports the following commands:
list-person
Lists all persons in the personal database.
new-person person-key
Creates a new person record.
open-person person-key
Opens the existing person record.
close-person
Closes the current person record.
list-person-field
Lists all the name-value pairs associated with the current person record.
person-put-field name value
Puts the value "value" in the field named "name" for the current person record.
person-get-field name
Gets the value associated with the field named "name" for the current person record.
person-delete-field name
Deletes the name-value pair named by "name" for the current person record.
list-performance
Lists all the performance records in the database.
new-performance person-key content-key date-time-key
Creates a new performance record based on the primary key
open-performance person-key content-key date-time-key
Opens an existing performance record based on the primary key.
close-performance
Closes the opened performance record.
performance-list-field
Lists all the name-value pairs for the current performance record.
performance-put-field name value
Puts the value "value" in the field named "name" for the current performance record.
performance-get-field name
Gets the value associated with the field named "name" .
performance-delete-field name
Deletes the name-value pair named by "name" for the current performance record.
Prototype API Reference
There are many classes that are useful to programs who wish to construct applications that will interoperate with the IMS management system. Some of these classes are listed here with a brief description of their most useful method calls.
user class
The User represents an individual in the IMS system. Every user has a user profile, preferences, group membership, etc. The User object is not persisted by itself, but is persisted through a UserInfo object that contains more user tracking information.
User(String userName)
Constructor
String getName()
Returns the user's login name. Note that this is not the user's "real" name. The real name of user is obtained this way:
PersonalData pd = u.getUserProfile().getPersonalData();
String fName = pd.getNameFamily(); // family name
String gName = pd.getNameGiven(); // given name(s)
long getID()
Returns the user's unique ID by which s/he is identified throughout the system.
UserProfile getUserProfile()
Returns the user's UserProfile .
Vector getGroups()
Returns a vector of the user's group memberships.
String getStartGroup()
Returns the name of the user's starting group.
void setStartGroup(String groupName)
Changes the name of the user's starting group.
void setProfile(String profileServer, long profileID)
This method assigns the profile information to the user object.
getPersonalData()
getPreferences()
getRecords()
Group Class
An IMS group represents a collection of people, resources, and additional sub-groups.
Group(String groupName, long parentGroupID)
Constructor
Vector getSubgroups()
Returns a vector of the identities of the subgroups.
Vector getResources()
Returns a vector of the identities of the resources.
String getHomepage()
Returns the group's home page (a URL).
void setHomepage(String homepage)
Assigns a new home page (URL) for the group.
User getOwner()
Returns the user ID of the group's owner.
void setOwner(User owner)
Assigns the user ID of the group's owner.
Vector getMembers()
Returns a vector of the identities of the group members.
String getCChannel()
Returns the name of the group-specific CHAT channel.
String getNChannel()
Returns the name of the group-specific notification channel. The notification channel carries managment style signals, such as the addition or removal of members, resources, and subgroups.
void setNChannel(String nChannel)
Assigns a new name for the group-specific notification channel.
boolean addMember(User user)
Adds a new user to the group, properly updating both the group and the
user record.
boolean removeMember(User user)
Removes a user from the group, properly updating both the group and the user record.
void addResource(Resource resource)
Adds a resource to the group.
void removeResource(Resource resource)
Removes a resource from the group.
void addSubGroup(Group child)
Adds the given group to the current group's list of subgroups.
void removeSubGroup(Group child)
Removes the given group from the current group's list of subgroups.
UserProfile Class
A UserProfile forms a collection of personal data, user preferences, and certifications. A UserProfile is serialized separately from the User object, but for ease-of-use is loaded and attached to the User object when the User object is loaded.
UserProfile(User user)
Constructor
PersonalData getPersonalData()
Returns the personal data associated with this profile.
Preferences getPreferences()
Returns the preferences associated with this profile.
Records getRecords()
Returns the user certification records.
Resource Class
An IMS Resource represents a collection of information about a learning resource, an object addressable by URL. Every resource is directly associated with a group and has meta-data associated with it.
Resource(String name, String url)
Constructor
String getURL()
void setURL(String url)
Meta-data getMeta-data()
void setMeta-data(Meta-data meta-data)
Vector getSignPosts()
Returns a vector of Sign Posts for the resource.
void setSignPosts(Vector signPosts)
Sets the resources vector of sign posts.
Vector getGroups()
Returns a list of groups to which this resource belongs.
SignPost Class
A Resource may contain a set of SignPosts which indicate the internal points at which it is willing to post progress notifications. The user who controls the resource can enable or disable these notifications and choose where notifications are to be sent. When the resource is activated it consults these signposts at each potential notification point. If the SignPost is enabled a notification message is sent to the user, channel or file indicated by the destination field. The signposts are associated with the Resource object. They may be edited at any time but go into effect on each subsequent activation of the resource. A SignPost contains the following fields:
name
Example: Frog_Dissection_3.5
description
Example: Send performance score when user has completed the heart dissection.
destination
Example: U:Ken_Schweller
enabled
Example: true
The user who controls this resource would see this signpost and all the others belonging to the resource when she first adds the resource or invokes a resource editing menu at some later time. The destination and enable fields would, for example, be set by checking them on a form. The Frog Dissection Resource would interpret the signpost in the example above to mean: Notify user Ken_Schweller according to his personal notification preferences when the user has reached sign post 'Frog_Dissection_3.5.'
SignPost()
Constructor.
SignPost(String sp)
Reconstructs a SignPost from its stringified representation.
void setName(String name)
void setDescription(String description)
void setDestination(String destination)
Destination may be a (U)ser, (C)hannel, or (F)ile according to the IMS Routing prefix conventions.
void setEnable(boolean enable)
String getName()
String getDescription()
String getDestination()
boolean getEnable()
String toString()
Converts the signpost to a string that can be easily transported, stored, or otherwise exchanged between systems.
RMI servers
There are three Java RMI servers that are activated at server start up time. The Message Router has no methods exposed as User APIs. It creates and continuously monitors a selected message channel. It routes each message on the channel to its appropriate destination which might be another channel, a file, or a user. In the case of messages directed to users the Router checks the user's notification preferences to determine how to proceed. Normally the notification would be by email, but forwarding of the message to another user, file, or channel is permitted. Its only method is run().
The IMS Server Coordinator Object represents the management entry point to the IMS system. Once connected to the system, through this object, functions such as login(), listUsers(), getGroups(), etc. are available, as well as methods to manipulate group membership, group organizational hierarchy, resource creation, etc.
Coordinator RMI Interface
void addResource(long resourceID, long groupID)
Adds a resource to the indicated parent group.
void addSubgroup(long newgroupID , long parentgroupID)
Adds a child group to the indicated parent group.
void addUserToGroup(User user, long groupID)
Adds a given user to the group indicated by the ID.
void changePassword(User user, String old, String new, String verify)
Changes the password of the given user.
Group createGroup(String groupname)
Creates a group.
Resource createResource(String name, String url, long groupID)
Creates a resource and add it to a group.
User createUser(String username, String password)
Creates a user with password.
void createUserProfile(long userID, String profileServer)
Creates a new profile for the given user.
Vector getActiveGroupUsers(long groupID)
Returns a vector of User ID's of active group members.
Group getGroup(long groupID)
Returns a Group object based on the group's unique ID.
Resource getResource(long resourceID)
Returns a Resource object based on the Resource's unique ID.
User getUser(long userID)
Returns a User object based on the user's unique ID.
Vector listGroups(String matchSubString)
Returns a list of available groups in the system.
Vector listResources(long groupID, String matchSubString)
Vector listUsers(String matchSubString)
Returns a list of available users in the system.
void login(String username, String password)
void logout(User user)
void removeResource(long resourceID, long groupID)
Removes a previously added resource from the indicated parent group.
void removeSubgroup(long groupID, long groupID)
Removes a previously added child group from the indicated parent group.
void removeUserFromGroup(User user, long groupID)
Removes a given user from the group indicated by the ID
void setUserProfile(long userID, String profileServer, long profileID)
Assigns an existing profile for the given user.
Channel Manager RMI Interface
boolean openChannel(String channelName)
Opens or creates a new Message Channel.
boolean closeChannel(String channelName)
Closes named channel if open.
String listChannels()
Listsall open channels by name.
boolean isChannelOpen(String channelName)
Determines if message channel is available.
String connectChannel(String channelName, int mode)
Returns handle to message channel if successful.
boolean disconnectChannel(String connection)
Disconnects from named channel.
boolean sendMessage(String connection, String message)
Sends asynchronous message to message channel using handle.
String waitMessage(String connection)
Synchronous call to message channel. Process waits until
a message arrives.
String getMessage(String connection)
Synchronous call to message channel. Process returns with or without a message.
boolean isMessageAvailable(String connection)
Determines whether a message is available on selected channel.
Useful Classes
Message Class
This class is useful for creating structured messages to be transmitted over IMS message channels. The TYPE of a message should, ideally be a common MIME type or expressed in some agreed upon MIME like format. The BODY of a message is normally plain ascii text or data, however specific applications might serialize objects, convert these to a String form, and push that result through the channel, knowing that the recipient understands the message type and will take steps to convert the "stringified" and serialized object back to its original form. Note: XML is the recommended syntax for the character-based messages.
To determine the TYPE and BODY of a message that was received:
Message msg = new Message( myManager.waitMessage( myHandle ) );
String type = msg.getType();
String body = msg.getBody();
To transmit a message with a particular type and body:
Message msg = new Message( "ims-chat/event", "Udo entered chat room" );
myManager.sendMessage( myHandle, msg.toString() );
Message(String type, String body)
Constructor
void append(String body)
Appends the given body text to the message.
void setType(String type)
Assigns a new type to the message format such as "application/purpose" .
void setBody(String body)
Assigns a new body to the message.
String getType()
Returns the type of the message.
String getBody()
Returns the body of the message.
String toString()
Messenger Class
This class provides a convenient interface to the IMS Channel Manager and Message_Router.
Messenger()
Constructor
void route(String, Message)
Routes a formatted Message to a user, channel, or file .
void route(String, String)
Routes a string message to a user, channel, or file using Routing Prefixes.
void routeToChannel(String, Message)
Routes formatted Message to named Message Channel.
void routeToChannel(String, String)
Routes string message to named Message Channel.
void routeToFile(String, Message)
Routes a formatted Message to a named File.
void routeToFile(String, String)
Routes a message to a named File.
void routeToUser(String, Message)
Routes a formatted Message to a user by name.
void routeToUser(String, String)
Routes a string message to a user by name.
void close()
Closes messenger and shutsdown connection to ims-router.
Resource Agent
The Resource Agent provides a resource with information about its user's identity and preferences. It informs a resource about the group it is in, other group members, which members are active, other group resources, and available message channels. By extending the Messenger class it provides a means for the resource to send, receive and route messages to other channels, users and files. Finally, it contains methods for getting and setting a resource's sign posts.
ResourceAgent(String resourcename, String username,
String groupname, String host)
Constructor
String getResourceName()
Vector getActiveMembers()
Gets IDs of group members currently on line.
Vector getActiveMembersByName()
Gets names of group members currently on line.
Vector getSignPosts()
Gets the Resource Sign Posts.
void setSignPosts(Vector signposts)
Resets the Resource Sign Posts.
String getGroupName()
Returns the name of the group.
long getGroupID()
Returns the group's unique ID.
Vector getGroupResources()
Returns a vector of the identities of the resources.
long getGroupOwner()
Returns the user ID of the group's owner.
Vector getGroupMembers()
Returns a vector of the identities of the group members.
String getGroupChatChannel()
Returns the name of the group-specific CHAT channel.
String getGroupNChannel()
Returns the name of the group-specific notification channel.
String getGroupReport()
Returns all group data in a formatted report.
String getUserName()
Gets the User's Login name.
long getUserID()
Gets the User's ID.
String getUserPreferredBrowser()
Gets the User's Preferred Browser.
String getUserLanguage()
Gets the User's Preferred Language.
String getUserEmail()
Gets the User's Email.
void quit()
Quits Agent, closes any opened channels.
CGI_MessageRouter
The CGI_MessageRouter is a servlet that responds to cgi post messages from web based applications allowing users to send messages via HTTP to the IMS message channels. An example of sending a message to the server in this fashion is presented in the concluding tutorial.
Prototype Utility Applications
Chat
The Chat Utility was designed to demonstrate the use of the the Message Channels as a tool for group collaboration. This chat is unique in that it does not depend on the use of socket connections to a dedicated chat server. Instead, messages from client chat applets are sent by RMI to a group's chat channel managed by the CORBA channel manager. The client also monitors this channel to intercept messages from other group members.
Message Board
The Message Board Utility is a basic threaded discussion list configured for each group. The servlet that manages the presentation consults each user's session information to determine their current group.
Message Service
The message center allows users to send messages to one another according to the recipients' personal notification preferences. Messages are posted to a channel monitored by the Router which looks up each users notification preferences in their personal profile and attempts to deliver the message accordingly. Note, this is quite different in concept from a simple email center.
Channel Spy
The channel spy utility allows a user to monitor messages sent to designated message channels. It is a useful testing and debugging tool during the application development process.
Resource Demos
History Test
The History Test demonstrates how data can be posted from an HTML form to an IMS message channel via a dedicated CGI_MessageRouter Servlet. See Fig. 1 for a diagram of the steps involved.
Collaborative Graph and Monitor
The Collaborative Graph demonstrates synchronous message passing between applications and the use of notification sign posts. Two or more students work in separate applications trying to match a mystery function given by their teacher and are able to 'push' functions to each other for viewing. As sign posts previously enabled by the instructor are encountered by each student notification events are generated and sent to a dedicated channel. This channel is attended by a Monitor program which does a statistical analysis on the information received.
Communicating with the Server: A Brief Tutorial
In this tutorial we will show how to use the Message, Messenger, CGI Message Router, Resource Agent, and Sign Post classes to communicate with the IMS server from various resource applications.
Posting HTML Form data to a Message Channel
For this example let's imagine that we are doing a class survey on TV viewing habits. We plan to collect our data using a simple HTML web form and post the data to a dedicated IMS message channel where a special statistics program will capture and summarize the results. We will focus in this example on the client end of this sequence and show how this posting can be done from the user's browser. We begin by setting up the following form leaving the form's 'action' value incomplete.
To complete the form all we need to know is the URL of the imsserver we are connecting to and the name of the message channel that is being monitored by the statistics program. Let's suppose that the server is at 'www.server.edu' and that we know the statistics program is listening on a channel named 'tv_survey'. We would complete the form as follows:
The action line tells us that we are posting our data to the 'cgimessagerouter' servlet located at 'www.server.edu'. The CGI Message Router will examine the hidden destination field to determine how to route the survey data. From the destination value 'C:tv_survey' it will determine that the body of the message (the name/value form pairs) is to be forwarded to a channel named 'tv_survey'.
We can test whether our form is posting data correctly by monitoring the 'tv_survey' channel with the Channel Spy utility accessible from the management bar of the prototype. Activate the Spy program and set it to the proper channel. After filling in the form in your browser and submitting the data, refresh the window containing the Spy program to see the data displayed .
Monitoring the Message Channel
The statistics program introduced in the preceding example needs to monitor the 'tv_survey' message channel and update its data base each time it intercepts a message. The following code shows how a TV_SurveyMonitor applet could use a Messenger Object to open a channel for monitoring.
import org.ims.msgchannel.rmi.Messenger;
import org.ims.msgchannel.Message;
...
public class TV_SurveyMonitor extends Applet implements Runnable
{
...
private Thread listener;
...
public void init()
{
...
}
public void start()
{
listener = new Thread(this);
listener.start();
}
public void run()
{
Messenger messenger = new Messenger("www.server.edu");
messenger.openChannel("tv_survey");
String mchannel =
messenger.connectChannel("tv_survey", "r");
while(true)
{
Message msg =
new Message( messenger.waitMessage(mchannel) );
String body = msg.getBody();
updateRecords(body);
}
}
public void updateRecords(String msg)
{
...
}
}
In this example the applet creates a 'listener' thread to monitor the 'tv_survey' channel. A Messenger object is created to open and connect the applet to the channel. The applet then enters a continual loop to wait for messages and update database records. Note that because of applet security this applet must originate from the same browser which hosts the IMS server.
Creating Signposts
In our final example we show how to add signposts to an existing program. Let's suppose we have written a 'Frog Dissection' applet and we wish to publish notifications when users have reached critical points in the program. We can identify each critical point and identify it with a signpost. For example, at the point where a student has finished dissecting the frog's brain we might like to send a message to his professor that he completed the task with some particular score. Here is some code that illustrates how such a signpost might be created.
SignPost sp;
sp = new SignPost();
sp.setName("Brain Dissection SP");
sp.setDescription("Send notification when user finishes dissecting brain.");
sp.setDestination(U:Ken Schweller);
sp.setEnable(true);
Sign Posts can be named in any way you wish, in this example the sign post is named 'Brain Dissection SP". The description indicates when a notification is to be sent. This information is displayed to users when they elect to enable or disable a resource's notifications from the Management bar on the prototypes main presentation page. The sign post description never appears to a user when the program is actually running. The destination indicates where the notification is to be sent, in this case to Ken Schweller according to his notification preferences, most likely email. This and any other sign posts created can be saved in a local vector as follows.
Vector signposts = new Vector();
signposts.addElement(sp);
When all the sign posts have been created they can be persisted in the associated Resource Object. This is most easily done using the "setSignPosts" method of the Resource Agent that knows exactly how to find and communicate with the programs associated Resource object.
String host = "www.imsserver.edu";
agent = new ResourceAgent("Frog Dissection", null, null, host);
agent.setSignPosts(signposts);
When the Frog Dissection program is activated by a user it must reload its sign post data from its associated Resource object once again using the Resource Agent. This reloading is necessary since individual signposts may have been either enabled or disabled from the Resource Notifications editor since the program was last run.
signposts = agent.getSignPosts();
When the user finishes dissecting the frog brain and it is time to report his score the program composes a message based on the user's name and score and calls its 'notify' method.
Message msg = new Message(user +" scored " + score+" on brain dissection.");
notify("Brain Dissection SP", msg, signposts);
An example notify method is presented below. This method searches for the 'brain dissection' signpost and determines whether it is currently enabled. If it is enabled it extracts from the sign post the proper destination and forwards the message to that location.
public boolean notify(String spname, Message msg,
Vector signposts)
{
SignPost sp;
for (int i=0; i
Here is a short multiple choice test on Midwest Geography based on the XML-Data Schema shown above. For demonstration purposes we can imagine that this schema is available from a repository at http://www.ims.org/schemas/tests/..
Midwest Geography Test
-
1
The Capital of Iowa is
Storm Lake
Sioux City
Des Moines
-
2
Lake Okoboji is located in
Kansas
Missouri
Minnesota
Iowa
A Schema for Multiple Choice Test Answers
The XML-Data Schema for reporting an individual's scores on a multiple choice test might look like this:
Actual packaged test results would look like this:
Midwest Geography Test
Bob Alcorn
19980528
Ken Schweller
-
1
Storm Lake
Des Moines
-
2
Iowa
Iowa
Schemas for Performance Data
Performance Information may be stored in a User's Profile at any time. The information might describe a person's performance over an entire academic program, a single course, a single test, or even how the person did on a single discrete exercise or question. The schema given here illustrates what such a performance profile might look like expressed in XML-data.
-
BVU-GEOLOGY-01-MOD-1234 US-NYS-LETTER-GRADE
C
BUENA-VISTA-UNIVERSITY
Schemas for Notifications
Notifications will be delivered over the IMS Message Channel using Structured Event messages as detailed in the API section on Messaging. There will be an inheritance hierarchy of structured event objects and each of which will also be expressible in XML-Data format. An XML-Data representation of a structured event message for notifying professor Schweller about Bob Alcorn's score on the geography test might look like this:
EDUCATION
NOTIFICATION
ASSESSMENT
DR-SCHWELLER
MW-GEO-TEST
BOB-ALCORN
19980528
2
1
50
Schemas for Navigation
Resources will post Navigation events to the Message Channel when their users reach those parts of the learning exercise that are marked by Sign Posts. These navigational messages are a special kind of Notification message and thus will have an XML representation similar to but extending that for Notifications presented above.
EDUCATION
NOTIFICATION
NAVIGATION
DR-SCHWELLER
MW-GEO-TEST
BOB-ALCORN
19980528
START-TEST
19981105T08:15:5
Reference Data Classes
This section will contain Corba and DCOM IDL for structured data such as test items. These and other data classes will be stored online at the IMS/NIST Meta-data Description Repository where they and other data classes used in communities of best practice will be able to visually and programmatically browse the collections of data classes.
Performance Data
Notifications
References
Dublin Core
The Dublin Core Metadata is at http://purl.oclc.org/metadata/dublin_core/
OMG
The Object Management Group is at http://www.omg.org/
ODMG
The Object Database Management Group is at http://www.odmg.org/
W3 RDF and XML
The World Wide Web Consortium (with links to the Resource Description Format and eXtensible Mark-up Language documentation) is at http://www.W3C.org/
NIST RBAC
The National Institute for Standards and Technology, Role Based Access Control is at http://hissa.ncsl.nist.gov/rbac/
Contributors
The following people have participated on the IMS Technical team providing input into the Specifications and prototype development.
Steve Griffin (COLLEGIS Research Institute)
Andy Doyle (International Thomson Publishers)
Bob Alcorn (Blackboard)
Brad Cox (George Mason University)
Frank Farance (Farance Inc)
John Barkley (NIST)
Ken Schweller (Buena Vista University)
Kirsten Boehner (COLLEGIS Research Institute)
Mike Pettit (Blackboard)
Neal Nored (IBM)
Tom Rhodes (NIST)
Tom Wason (UNC)
Udo Schuermann (Blackboard)
Thanks
Many people have contributed to the development of this technical specification. We would like to thank the participants of the Requirements meeting, technical meetings, design sessions, and focus group. We would also like to thank the Advisory Board members for their support and insight into the progress of the project's goals:
Special Thanks
We'd like to offer special thanks to the following individuals and organizations for their support and guidance:
Mark Resmer (California State University - Sonoma)
Denis Newman (Center for Distributed Learning)
Lou Zweier (Center for Distributed Learning)
Rachel Smith (Center for Distributed Learning)
Carol Twigg (Educom)
Investment Member Companies:
Apple Computer
Asymetrix
AT&T Learning Network
Buena Vista University
The California State University
COLLEGIS
COLLEGIS Research Institute
Committee on Institutional Cooperation (CIC)
Educational Testing Service
Empower Corporation
Farance, Inc.
George Mason University
IBM Education
International Thomson Publishing
Joint Information Systems Committee (JISC)
KPMG Peat Marwick LLP
Miami-Dade Community College
Microsoft
National Institute of Standards and Technology (NIST)
Oracle
PeopleSoft
Simon & Schuster
Sun Microsystems
UNISYS
University of Californiz
University of Michigan
Universtiy of North Carolina at Chapel Hill
U.S. Department of Defense
@learning
Appendix A: Interface Descriptions
Group Service Interfaces
Interface Descriptions
Module Group
The ICertification Interface
A Certification is an abstract object reference encapsulating the validation that a user holds credentials granted to him or her by the certifying agency. The Certification can be self-contained data, including such things as expiration date, or it could be an object with a Validate() method which would contact the certifying agency to check the status of the user's certification.
The User Attribute
This is a reference to the IMSUser that owns this Certification.
The IGroup Interface
The Group is the central abstraction of the IMS model. A Group is a set of GroupMembers, Resources, and Tools that can communicate with one another through a MessageChannel. GroupMembers have different roles such as leader, TA, learner, guest, etc. which determine their rights to access group tools, resources, and functions.
mChannelManager
mResourceCoordinator
This is the ResourceCoordinator that owns the Group
mGroupMembers
These are the GroupMembers that are assigned to this Group.
mParts
This is the collection of Parts, or Resources, for a group.
CreateGroup
This method creates a sub-group. The default behavior is to cascade the members from the parent group and not to cascade the resources from the parent group. If the owner parameter is passed as null, the owner of the parent group is assigned ownership of this group.
CreateResource
This method adds a resource object to a group. The resource object can either be a reference to a resource or the resource itself, data and all.
DeleteGroup
This method removes a subgroup from a group. All of the contents of the group will be deleted unless there are imposed constraints due to relationships the sub-group has with other objects in the system.
DeleteResource
This method removes a resource from a group. If this is an actual resource, data and all, instead of a moniker resource, then the resource is removed from the IMS system entirely.
CreateGroupMember
This method associates an User with a group. The member can then be assigned the roles that they play in the group. These roles are inherited from the generic roles defined in the Role Based Access Control service of the ResourceCoordinator. See the documentation of ResourceCoordinator and the associated security interfaces for more information.
DeleteGroupMember
This method removes a GroupMember from a group. The User represented by the GroupMember object is not affected.
The IGroupMember Interface
mGroup
This is the group that this group member belongs to.
mSession
The IUser Interface
mResourceCoordinator
This is the ResourceCoordinator that has control over this User definition.
mPersonalData
This is a reference to the PersonalData owned by this User.
mPreferences
This is a reference to the Preferences owned by this User.
mCertifications
This is a reference to the collection of Certifications owned by this User.
The IResourceCoordinator interface
mUsers
This is the collection of users that are defined within this ResourceCoordinator. All assignments of Users to Groups owned by this ResourceCoordinator must come from this pool.
mGroups
This is the collection of root level groups owned by a ResourceCoordinator.
RegisterUser
Create a user in the context of this ResourceCoordinator.
ShowCatalog
IsEnrolled
CertifyUser
CORBA IDL
#ifndef _GROUP_IDL_
#define _GROUP_IDL_
module Group
{
interface Certification
{
attribute User mUser;
};
interface Group
{
exception ObjectNotFound{};
attribute ChannelManager mChannelManager;
attribute ResourceCoordinator mResourceCoordinator;
sequence mGroupMembers;
sequence mParts;
Group CreateGroup( in boolean cascadeUsers,
in boolean cascadeResources,
in User owner );
void CreateResource(in Resource resource);
void DeleteGroup( in Group group )
raises( ObjectNotFound );
void DeleteResource(in Resource resource )
raises( ObjectNotFound );
GroupMember CreateGroupMember( in User user );
void DeleteGroupMember( in GroupMember groupMember )
raises( ObjectNotFound );
};
interface GroupMember
{
attribute Group mGroup;
attribute Session mSession;
};
interface User
{
attribute ResourceCoordinator mResourceCoordinator;
attribute Property::Property mPersonalData;
attribute Property::Property mPreferences;
sequence mCertifications;
};
interface ResourceCoordinator
{
sequence mUsers;
sequence mGroups;
void RegisterUser( in User user );
void ShowCatalog();
boolean IsEnrolled( in User user );
void CertifyUser( in User user );
};
};
#endif // _GROUP_IDL_
DCOM IDL
Session Service Interfaces
Interface Descriptions
CORBA IDL
DCOM IDL
Messaging Service Interfaces
Origin of Interfaces
The following information is based entirely on the Object Management Groups proposed specification of the Common Object Services Notification Service. The only changes that have been made, other than the addition of IMS context information, is the harmonization of interface signatures with the rest of the IMS and the possible removal of some low level CORBA dependencies.
Interface Descriptions
The IMSNotification Module
The IMSNotification module defines the Structured Event data type, along with a data type used for transmitting sequences of Structured Events. In addition, this module provides constant declarations for each of the standard quality of service (QoS) and administrative properties supported by all Notification Service implementations. Some properties also have associated constant declarations which indicate their possible settings. Finally, administrative interfaces are defined for managing sets of QoS and administrative properties.
The STRUCTUREDEVENT Data Structure
The STRUCTUREDEVENT data structure defines the fields which comprise a Structured Event. The following subsections briefly describe each of these fields. A detailed description of Structured Events is provided in section 2.2.
Fixed Header
The following fields make up the fixed portion of the header of every Structured Event.
domainType
The domainType field contains a string which identifies the vertical industry domain (e.g., telecommunications, healthcare, finance, etc.) within which the type of event which characterizes a given Structured Event is defined. The definition of this field enables each vertical domain to define their own set of event types without worrying about name collisions with those defined by other vertical domains.
eventType
The eventType field contains a string which identifies the type of event contained within a given Structured Event. This name should be unique among all event types defined within a given vertical domain, which is identified by the domain_type field.
eventName
The eventName field contains a string which names a specific instance of Structured Event. This name is not interpreted by any component of the Notification Service, and thus the semantics associated with it can be defined by end-users of the service. This field can be used, for instance, to associate names with individual Structured Events which can be used to uniquely identify an instance of a particular type of Structured Event within a given installation of the Notification Service.
variableHeader
The remainder of the header of a Structured Event is contained within the variableHeader field. The data type of this field is a sequence of name-value pairs, where each name is a string and each value a CORBA::Any. While this field can essentially contain any name-value pairs which users of the service deem to be useful to provide in the header of a Structured Event, standard names and associated value types are defined in Table 2-3 on page 35 of this document. The standard variable header fields defined there provide QoS related information about the current Structured Event that should override other QoS settings within the channel when objects within the channel process the current Structured Event.
Body of a Structured Event
The body of a Structured Event is intended to contain the contents of an instance of a Structured Event being published by a Notification Service supplier. Its contents are broken down into two fields: the filterableData and the remainderOfBody. The purpose of each of these fields is defined below.
filterableData
The filterableData portion of the body of a Structured Event is a sequence of name-value pairs, where name is of type string and the value is a CORBA::Any. The main purpose of this portion of the event body is to provide a convenient structure into which event body fields upon which filtering is likely to be performed can be placed. It is anticipated that mappings of standard event types to the Structured Event will be defined such that standard event body field names correspond to values of well-known data types. Examples of such mappings for common event types used within the Telecommunications industry are provided in section 4 of this document. In addition, end users can define their own name-value pairs which comprise the filterable portion of any proprietary event types.
remainderOfBody
The remainderOfBody portion of the event body is intended to hold event data upon which filtering is not likely to be performed. From a logical point of view, the interesting fields of the event data should be placed into the filterableData portion, and the rest of the event placed here. Obviously it is not possible to predict what portion of the event will be interesting (or not) to all consumers. The division of the event body within the structured event in this fashion merely provides a hint to consumers. It is still possible to perform filtering on the contents of the remainderOfBody portion of the event body, however this will require decomposing the Any data structure which contains this portion into actual typed data elements, using the typecode contained within the Any. Thus filtering on this portion of the event body is likely to be less efficient than filtering on the filterable_data portion.
The EventBatch Data Type
The IMSNotification module defines the EventBatch data type as a sequence of Structured Events. The IMSNotifyComm module defined in section 3.3 defines interfaces which support the transmission and receipt of sequences of Structured Events within a single operation. Such a sequence of Structured Events transmitted as a unit is referred to as an event batch, and is of the EventBatch data type.
QoS and Administrative Constant Declarations
The IMSNotification module declares several constants related to QoS properties of event transmission, and administrative properties of notification channels. The meanings of each property related to QoS and its associated values is described in detail in section 2.5.5 of this document. The meanings of each property related to channel administration and its associated values is described in section 2.5.7.
The IQoSAdmin Interface
The IQoSAdmin interface defines operations which enable clients to get and set the values of QoS properties. It also defines an operation that can verify whether or not a set of requested QoS property settings can be satisfied, along with returning information about the range of possible settings for additional QoS properties. IQoSAdmin is intended to be an abstract interface which is inherited by the IProxy, IAdmin, and IEventChannel interfaces defined in the IMSNotifyChannelAdmin and IMSTypedNotifyChannelAmin modules. The semantics of the operations supported by this interface are defined below.
GetQoS
The GetQoS operation takes no input parameters, and returns a sequence of name-value pairs which encapsulates the current quality of service settings for the target object (which could be an Event Channel, Admin, or Proxy object).
SetQoS
The SetQoS operation takes as an input parameter a sequence of name-value pairs which encapsulates quality of service property settings that a client is requesting that the target object (which could be an Event Channel, Admin, or Proxy object) support as its default quality of service. If the implementation of the target object is not capable of supporting any of the requested quality of service settings, or if any of the requested settings would be in conflict with a QoS property defined at a higher level of the object hierarchy with respect to QoS (see section 2.5.6), the UnsupportedQoS exception is raised. This exception contains as data a sequence of data structures, each of which identifies the name of a QoS property in the input list whose requested setting could not be satisfied, along with an error code and a range of settings for the property which could be satisfied. The meanings of the error codes which might be returned are described in Table 2-4.
ValidateQos
The ValidateQos operation accepts as input a sequence of QoS property name-value pairs which specify a set of QoS settings that a client would like to know if the target object is capable of supporting. If the any of the requested settings could not be satisfied by the target object, the operation raises the UnsupportedQoS exception. This exception contains as data a sequence of data structures, each of which identifies the name of a QoS property in the input list whose requested setting could not be satisfied, along with an error code and a range of settings for the property which could be satisfied. The meanings of the error codes which might be returned are described in Table 2-4. If all requested QoS property value settings could be satisfied by the target object, the operation returns successfully (without actually setting the QoS properties on the target object) with an output parameter that contains a sequence of PropertyRange data structures. Each element in this sequence includes the name of a an additional QoS property supported by the target object which could have been included on the input list and resulted in a successful return from the operation., along with the range of values that would have been acceptable for each such property.
The IAdminPropertiesAdmin Interface
The IAdminProperitesAdmin interface defines operations which enable clients to get and set the values of administrative properties. This interface is intended to be an abstract interface which is inherited by the Event Channel interfaces defined in the IMSNotifyChannelAdmin and IMSTypedNotifyChannelAmin modules. The semantics of the operations supported by this interface are defined below.
GetAdmin
The GetAdmin operation takes no input parameters, and returns a sequence of name-value pairs which encapsulates the current administrative settings for the target channel.
SetAdmin
The SetAdmin operation takes as an input parameter a sequence of name-value pairs which encapsulates administrative property settings that a client is requesting that the target channel support. If the implementation of the target object is not capable of supporting any of the requested administrative property settings, the UnsupportedAdmin exception is raised. This exception has associated with it a list of name-value pairs of which each name identifies an administrative property whose requested setting could not be satisfied, and each associated value the closest setting for that property which could be satisfied.
The IMSNotifyFilter Module
The IMSNotifyFilter module defines the interfaces supported by the filter objects used by the Notification Service. Two different types of filter objects are defined here. The first type support the IFilter interface and encapsulate the constraints which will be used by a proxy object associated with a notification channel in order to make decisions about which events to forward, and which to discard. The second type support the IMappingFilter interface and encapsulate constraints along with associated values, whereby the constraints determine whether a proxy object will alter the way it treats each event with respect to a particular property of the event, and the value specifies the property value the proxy would apply to each event which satisfies the associated constraint. In addition to the two types of filter object interface defined in this module, the IMSNotifyFilter module also defines the IFilterFactory interface which supports the operations required to create each type of filter object, and the IFilterAdmin interface which supports operations which enable an interface (IProxy or IAdmin) which inherits it to manage a list of IFilter instances.
The IFilter Interface
The IFilter interface defines the behaviors supported by objects which encapsulate constraints used by the proxy objects associated with an event channel in order to determine which events they receive will be forwarded, and which will be discarded. Each object supporting the IFilter interface can encapsulate a sequence of any number of constraints. Each event received by a proxy object which has one or more objects supporting the IFilter interface associated with it must satisfy at least one of the constraints associated with one of its associated IFilter objects in order to be forwarded (either to another proxy object or to the consumer, depending on the type of proxy the filter is associated with), otherwise it will be discarded. Each constraint encapsulated by a filter object is a structure comprised of two main components. The first component is a sequence of data structures, each of which indicates an event type comprised of a domain and a type name. The second component is a boolean expression over the properties of an event, expressed in some constraint grammar (more on this below). For a given constraint, the sequence of event type structures in the first component nominates a set of event types to which the constraint expression in the second component applies. Each element of the sequence can contain strings which will be matched for equality against the domainName and typeName fields of each event being evaluated by the filter object, or it could contain strings with wildcard symbols (*), indicating a pattern match should be performed against the type contained in each event, rather than a comparison for equality when determining if the boolean expression should be applied to the event, or the event should simply be discarded without even attempting to apply the boolean expression. Note that an empty sequence included as the first component of a constraint implies that the associated expression applies to all types of events, as does a sequence comprised of a single element whose domain and type name are both set to either the empty string or else the wildcard symbol alone contained in quotes. The constraint expressions associated with a particular object supporting the IFilter interface are expressed as strings which obey the syntax of a particular constraint grammar (i.e. a BNF). Every conformant implementation of this service must support constraint expressions expressed in the default constraint grammar described in section 2.4. In addition, implementations may support other constraint grammars, and/or users of this service may implement their own filter objects which allow constraints to be expressed in terms of an alternative constraint grammar. As long as such user-defined filter objects support the IFilter interface, they can be attached to Proxy or Admin objects in the same fashion as the default IFilter objects supported by the implementation of the service are, and the channel should be able to use them to filterevents in the same fashion. The IFilter interface supports the operations required to manage the constraints associated with an object instance which supports the interface, along with a readonly attribute which identifies the particular constraint grammar in which the constraints encapsulated by this object have meaning. In addition, the IFilter interface supports three variants of the match operation which can be invoked by an associated proxy object upon receipt of an event (the specific variant selected depends upon whether the event is received in the form of an Any, a Structured Event, or a Typed Event), to determine if the event should be forwarded or discarded, based on whether or not the event satisfies at least one criteria encapsulated by the filter object. The IFilter interface also supports operations which enable a client to associate with the target filter object any number of callbacks which are notified each time there is a change to the list of event types which the constraints encapsulated by the filter object could potentially cause proxies to which the filter is attached to receive. Operations are also defined to support administration of this callback list by unique identifier. The operations supported by the IFilter interface are described in more detail within the following subsections.
constraintGrammar
The constraintGrammar attribute is a readonly attribute which identifies the particular grammar within which the constraint expressions encapsulated by the target filter object have meaning. The value of this attribute is set upon creation of a filter object instance, based on the input provided to the factory creation operation for the filter instance.
The dependency of a filter object on its constraints being expressed within a particular constraint grammar manifests itself within the implementation of the Match operations described below, which must be able to parse the constraints to determine whether or not a particular event satisfies one of them.
Every conformant implementation of the Notification Service must support an implementation of the IFilter interface which supports the default constraint grammar described in section 2.4. The value which the constraintGrammar attribute is set to in the case the target filter object supports this default grammar will be EXTENDED_TCL. In addition, implementations and/or end users may provide additional implementations of the IFilter interface which support different constraint grammars, and thus would set the constraintGrammar attribute to a different value upon creation of such a filter object.
AddContraints
The AddConstraints operation is invoked by a client in order to associate one or more new constraints with the target filter object. The operation accepts as input a sequence of constraint data structures, each element of which consists of a sequence of event type structures and a constraint expressed within the constraint grammar supported by the target object. Upon processing each constraint, the target object associates a numeric identifier with the constraint that is unique among all constraints it encapsulates. If any of the constraints in the input sequence is not a valid expression within the supported constraint grammar, the InvalidConstraint exception is raised. This exception contains as data the specific constraint expression that was determined to be invalid. Upon successful processing of all input constraint expressions, the AddConstraints operation returns a sequence in which each element will be a structure including one of the input constraint expressions, along with the unique identifier assigned to it by the target filter object.
Note that the semantics of the AddConstraints operation are such that its side-effects are performed atomically upon the target filter object. Once add_constraints is invoked by a client, the target filter object is temporarily disabled from usage by any proxy object it may be associated with. The operation is then carried out, either successfully adding all of the input constraints to the target object or none of them (in the case one of the input expressions was invalid). Upon completion of the operation, the target filter object is effectively re-enabled and can once again be used by associated filter objects in order to make event forwarding decisions.
ModifyConstraints
The ModifyConstraints operation is invoked by a client in order to modify the constraints associated with the target filter object. This operation can be used both to remove constraints currently associated with the target filter object, and to modify the constraint expressions of constraints which have previously been added to the target filter object.
The operation accepts two input parameters. The first input parameter is a sequence of numeric values which are each intended to be the unique identifier associated with one of the constraints currently encapsulated by the target filter object. If all input values supplied within a particular invocation of this operation are valid, then the specific constraints identified by the values contained in the first input parameter will be deleted from the list of those encapsulated by the target filter object.
The second input parameter to this operation is a sequence of structures, each of which contains a constraint structure and a numeric value. The numeric value contained by each element of the sequence is intended to be the unique identifier associated with one of the constraints currently encapsulated by the target filter object. If all input values supplied within a particular invocation of this operation are valid, then the constraint expression associated with the already encapsulated constraint identified by the numeric value contained within each element of the input sequence will be modified to the new constraint expression that is contained within the same sequence element.
If any of the numeric values supplied within either of the two input sequences does notcorrespond to the unique identifier associated with some constraint currently encapsulated by the target filter object, the ConstraintNotFound exception is raised. This exception contains as data the specific identifier which was supplied as input but did not correspond to the identifier of some constraint encapsulated by the target object. If any of the constraint expressions supplied within an element of the second input sequence is not a valid expression in terms of the constraint grammar supported by the target object, the InvalidConstraint exception is raised. This exception contains as data the specific constraint that was determined to be invalid. Note that the semantics of the ModifyConstraints operation are such that its side-effects are performed atomically upon the target filter object. Once ModifyConstraints is invoked by a client, the target filter object is temporarily disabled from usage by any proxy object it may be associated with. The operation is then carried out, either successfully deleting all of the constraints identified in the first input sequence and modifying those associated with constraints identified in the second input sequence, or performing no side effects to the target object (in the case one of the inputs was invalid). Upon completion of the operation, the target filter object is effectively re-enabled and can once again be used by associated filter objects in order to make event forwarding decisions.
GetConstraints
The GetConstraints operation is invoked to return a sequence of a subset of the constraints associated with the target filter object. The operation accepts as input a sequence of numeric values which should correspond to the unique identifiers of constraints encapsulated by the target object. If one of the input values does not correspond to the identifier of some encapsulated constraint, the ConstraintNotFound exception is raised, containing as data the numeric value that did not correspond to some constraint. Upon successful completion, this operation returns a sequence of data structures, each of which contains one of the input identifiers along with its associated constraint.
GetAllConstraints
The GetAllConstraints operation returns all of the constraints currently encapsulated by the target filter object. The return value of this operation is a sequence of structures, each of which contains one of the constraints encapsulated by the target object along with its associated unique identifier.
RemoveAllConstraints
The RemoveAllConstraints operation is invoked to remove all of the constraints currently encapsulated by the target filter object. Upon completion, the target filter object will still exist but have no constraints associated with it.
Destroy
The Destroy operation destroys the target filter object, invalidating its object reference.
Match
The Match operation evaluates the filter constraints associated with the target filter object against an instance of an event supplied to the channel in the form of a CORBA::Any. The operation accepts as input a CORBA::Any which contains an event to be evaluated, and returns a boolean value which will be TRUE in cases where the input event satisfies one of the filter constraints, and FALSE otherwise. The act of determining whether or not a given event passes a given filter constraint is specific to the type of grammar in which the filter constraint is specified. Thus, this operation will need to be re-implemented for each supported grammar.
If the input parameter contains data that the match operation is not designed to handle, the UnsupportedFilterableData exception will be raised. An example of this would be if the filterable data contained a field whose name corresponds to a standard event field that has a numeric value, but the actual value associated with this field name within the event is a string.
MatchStructured
The MatchStructured operation evaluates the filter constraints associated with the target filter object against an instance of an event supplied to the channel in the form of a Structured Event. The operation accepts as input a data structure of type IMSNotification::StructuredEvent which contains an event to be evaluated, and returns a boolean value which will be TRUE in cases where the input event satisfies one of the filter constraints, and FALSE otherwise. The act of determining whether or not a given event passes a given filter constraint is specific to the type of grammar in which the filter constraint is specified. Thus, this operation will need to be re-implemented for each supported grammar.
If the input parameter contains data that the match operation is not designed to handle, the UnsupportedFilterableData exception will be raised. An example of this would be if the filterable data contained a field whose name corresponds to a standard event field that has a numeric value, but the actual value associated with this field name within the event is a string.
MatchTyped
The Match operation evaluates the filter constraints associated with the target filter object against an instance of an event supplied to the channel in the form of a typed event. The operation accepts as input a sequence of name-value pairs which contains the contents of the event to be evaluated, and returns a boolean value which will be TRUE in cases where the input event satisfies one of the filter constraints, and FALSE otherwise. The act of determining whether or not a given event passes a given filter constraint is specific to the type of grammar in which the filter constraint is specified. Thus, this operation will need to be re-implemented for each supported grammar.
If the input parameter contains data that the Match operation is not designed to handle, the UnsupportedFilterableData exception will be raised. An example of this would be if the filterable data contained a field whose name corresponds to a standard event field that has a numeric value, but the actual value associated with this field name within the event is a string.
AttachCallback
The AttachCallback operation accepts as input the reference to an object supporting the IMSNotifyComm::INotifySubscribe interface, and returns a numeric value assigned to this callback that is unique to all such callbacks currently associated with the target object. This operation is invoked to associate with the target filter object an object supporting the IMSNotifyComm::INotifySubscribe interface. This interface is inherited by all supplier interfaces (either those that are clients of a notification channel, or those that are proxy objects within a notification channel) defined by the Notification Service, and supports a SubscriptionChange operation. After this operation has been successfully invoked on a filter object, each time the set of constraints associated with the target filter object is modified (either by an invocation of its AddConstraints or its ModifyConstraints operations), the filter object will invoke the SubscriptionChange object of all its associated callback objects in order to inform suppliers to which the target filter object is attached of the change in the set of event types to which clients of the filter object subscribe. This enables suppliers to make intelligent decisions about which types of events it should actually produce, and which it can suppress the production of.
DetachCallback
The DetachCallback operation accepts as input a numeric value which should be one of the unique identifiers associated with one of the callback objects attached to the target filter object. If the input value does not correspond to the unique identifier of a callback object currently attached to the target filter object, the CallbackNotFound exception is raised. Otherwise, the callback object to which the input value corresponds is removed from the list of those associated with the target filter object, so that subsequent changes to the event type subscription list encapsulated by the target filter object will not be propagated to the callback object which is being detached.
GetCallbacks
The GetCallbacks operation accepts no input parameters and returns the sequence of all unique identifiers associated with callback objects attached to the target filter object.
The IMappingFilter Interface
The IMappingFilter interface defines the behaviors of objects which encapsulate a sequence of constraint-value pairs, where each constraint is a structure of the same type as that described in the previous section, and each value represents a possible setting of a particular property of an event. Note that setting of a particular property is not intended to imply that any contents of the event will be altered as a result of applying a mapping filter, but rather the way a proxy treats the event with respect to a particular property (i.e., priority or lifetime) could change. Upon receiving each event, a proxy object with an associated object supporting the IMappingFilter interface will invoke the appropriate Match operation variant (depending upon whether the event is received in the form of an untyped event, a Structured Event, or a typed event) on the mapping filter object in order to determine how it should modify a particular property value associated with the event to one of the values associated with one of the constraints encapsulated by the mapping filter. Internally, the mapping filter object applies the constraints it encapsulates to the event in order to determine whether or not the events property should be modified to one of the values associated with a constraint, or else the default value associated with the mapping filter.
Each instance of an object supporting the IMappingFilter interface is typically associated with a specific event property. For instance, in this specification IMappingFilter object instances are used to affect the properties of priority and lifetime for events received by a proxy supplier object. Each event received by a proxy object which has an object supporting the IMappingFilter interface associated with it must satisfy at least one of the constraints associated with the IMappingFilter object in order to have its property value modified, otherwise the property will remain unchanged. A specific instance supporting the IMappingFilter interface typically applies its encapsulated constraints in an order which begins with the best possible property setting (e.g., the highest priority or the longest lifetime), and ends with the worst possible property setting. As soon as a matching constraint is encountered, the associated value is returned as an output parameter and the proxy which invoked the operation proceeds to modify the property of the event to the new value.
The constraint expressions associated with a particular object supporting the IMappingFilter interface are expressed as strings which obey the syntax of a particular constraint grammar (i.e. a BNF). Every conformant implementation of this service must support constraint expressions expressed in the default constraint grammar described in section 2.4. In addition, implementations may support other constraint grammars, and/or users of this service may implement their own filter objects which allow constraints to be expressed in terms of an alternative constraint grammar. As long as such user-defined filter objects support the IMappingFilter interface, they can be attached to proxy objects in the same fashion as the default IMappingFilter objects supported by the implementation of the service are, and the channel should be able to use them to potentially affect the properties of events in the same fashion.
The IMappingFilter interface supports the operations required to manage the constraint-value pairs associated with an object instance which supports the interface. In addition, the IMappingFilter interface supports a readonly attribute which identifies the particular constraint grammar in which the constraints encapsulated by this object have meaning. The IMappingFilter interface also supports a readonly attribute which identifies the typecode associated with the datatype of the specific property value it is intended to affect, and another readonly attribute which holds the default value which will be returned as the result of a match operation in cases when the event in question is found to satisfy none of the constraints encapsulated by the mapping filter. Lastly, the IMappingFilter interface supports three variants of the operation which will be invoked by an associated proxy object upon receipt of an event, to determine how the property of the event which the target mapping filter object was designed to affect should be modified.
The operations supported by the IMappingFilter object are described in more detail within the following subsections.
constraintGrammar
The constraintGrammar attribute is a readonly attribute which identifies the particular grammar within which the constraint expressions encapsulated by the target filter object have meaning. The value of this attribute is set upon creation of a mapping filter object instance, based on the input provided to the factory creation operation for the mapping filter instance.
The dependency of a filter object on its constraints being expressed within a particular constraint grammar manifests itself within the implementation of the Match operations described below, which must be able to parse the constraints to determine whether or not a particular event satisfies one of them.
Every conformant implementation of the Notification Service must support an implementation of the MappingFilter object which supports the default constraint grammar described in section 2.4. The value which the constraintGrammar attribute is set to in the case the target filter object supports this default grammar will be EXTENDED_TCL. In addition, implementations and/or end users may provide additional implementations of the IMappingFilter interface which support different constraint grammars, and thus would set the constraintGrammar attribute to a different value upon creation of such a filter object.
valueType
The valueType attribute is a readonly attribute which identifies the datatype of the property value which the target mapping filter object was designed to affect. Note that the factory creation operation for mapping filter objects accepts as an input parameter the defaultValue to associate with the mapping filter instance. This defaultValue is a CORBA::Any. Upon creation of a mapping filter, the Typecode associated with the defaultValue is abstracted from the CORBA::Any, and its value is assigned to this attribute. The valueType attribute thus serves mainly as a convenience for clients attempting to examine the state of a mapping filter object.
defaultValue
The defaultValue attribute is a readonly attribute that will be the output parameter returned as the result of any Match operation during which the input event is found to satisfy none of the constraints encapsulated by the mapping filter. within which the constraints encapsulated by the target filter object have meaning. The value of this attribute is set upon creation of a mapping filter object instance, based on the input provided to the factory creation operation for the mapping filter instance.
AddMappingContraints
The AddMappingConstraints operation is invoked by a client in order to associate specific mapping constraints with the target filter object. Note that a mapping constraint is comprised of a constraint structure paired with an associated value. The operation accepts as input one parameter that is a sequence of constraint-value pairs. Each constraint in this sequence must be expressed within the constraint grammar supported by the target object, and each associated value must be of the data type indicated by the valueType attribute of the target object.
Upon processing the each element in the input sequence, the target object associates a numeric identifier with this constraint-value pair that is unique among all those that it encapsulates. If any of the constraint expressions in the input sequence is not a valid expression within the supported constraint grammar, the InvalidConstraint exception is raised. This exception contains as data the specific constraint that was determined to be invalid. If any of the values supplied in the input sequence is not of the same datatype as that indicated by the valueType attribute associated with the target object, the InvalidValue exception is raised. This exception contains as data both the invalid value and its corresponding constraint in the first input sequence. Upon successful processing of all input constraints, the addMappingConstraints operation returns a sequence in which each element will be a structure including one of the input constraint expressions, its corresponding value, and the unique identifier assigned to this constraint-value pair by the target filter object.
Note that the semantics of the AddMappingConstraints operation are such that its side-effects are performed atomically upon the target filter object. Once AddMappingConstraints is invoked by a client, the target filter object is temporarily disabled from usage by any proxy object it may be associated with. The operation is then carried out, either successfully adding all of the input constraint-value pairs to thetarget object or none of them (in the case one of the input expressions or values was invalid). Upon completion of the operation, the target filter object is effectively re-enabled and can once again be used by associated filter objects in order to make event property mapping decisions.
ModifyMappingConstraints
The ModifyMappingConstraints operation is invoked by a client in order to modify the constraint-value pairs associated with the target filter object. This operation can be used both to remove constraint-value pairs currently associated with the target filter object, and to modify the constraints and/or values of constraint-value pairs which have previously been added to the target filter object.
The operation accepts two input paramaters. The first input parameter is a sequence of numeric values which are each intended to be the unique identifier associated with one of the constraint-value pairs currently encapsulated by the target filter object. If all input values supplied within a particular invocation of this operation are valid, then the specific constraint-value pairs identified by the values contained in the first input parameter will be deleted from the list of those encapsulated by the target filter object. The second input parameter to this operation is a sequence of structures, each of which contains a constraint structure, an Any value, and a numeric identifier. The numeric identifier contained by each element of the sequence is intended to be the unique identifier associated with one of the constraint-value pairs currently encapsulated by the target filter object. If all input values supplied within a particular invocation of this operation are valid, then the constraint associated with the already encapsulated constraint-value pair identified by the numeric identifier contained within each element of the input sequence will be modified to the new constraint that is contained within the same sequence element. Likewise, the data value associated with the already encapsulated constraint-value pair identified by the numeric identifier contained within each element of the input sequence will be modified to the new data value that is contained in the same element of the sequence.
If any of the numeric identifiers supplied within either of the two input sequences does not correspond to the unique identifier associated with some constraint-value pairs currently encapsulated by the target filter object, the ConstraintNotFound exception is raised. This exception contains as data the specific identifier which was supplied as input but did not correspond to the identifier of some constraint-value pair encapsulated by the target object. If any of the constraint expressions supplied within an element of the second input sequence is not a valid expression in terms of the constraint grammar supported by the target object, the InvalidConstraint exception is raised. This exception contains as data the specific constraint that was determined to be invalid. If any of the values supplied in the second input sequence is not of the same datatype as that indicated by the value_type attribute associated with the target object, the InvalidValue exception is raised. This exception contains as data both the invalid value and its corresponding constraint expression.
Note that the semantics of the ModifyMappingConstraints operation are such that its side-effects are performed atomically upon the target filter object. Once ModifyMappingConstraints is invoked by a client, the target filter object is temporarily disabled from usage by any proxy object it may be associated with. The operation is then carried out, either successfully deleting all of the constraint-value pairs identified in the first input sequence and modifying the constraints and values associated with constraints identified in the second input sequence, or performing no side effects to the target object (in the case one of the inputs was invalid). Upon completion of the operation, the target filter object is effectively re-enabled and can once again be used by associated filter objects in order to make event property mapping decisions.
GetMappingConstraints
The GetMappingConstraints operation is invoked to return a sequence of a subset of the constraint-value pairs associated with the target filter object. The operation accepts as input a sequence of numeric values which should correspond to the unique identifiers of constraint-value pairs encapsulated by the target object. If one of the input values does not correspond to the identifier of some encapsulated constraint-value pair, the ConstraintNotFound exception is raised, containing as data the numeric value that did not correspond to some such pair. Upon successful completion, this operation returns a sequence of data structures, each of which contains one of the input identifiers along with its associated constraint structure and constraint value.
GetAllMappingConstraints
The GetAllMappingConstraints operation returns all of the constraint-value pairs currently encapsulated by the target filter object. The return value of this operation is a sequence of structures, each of which contains one of the constraints encapsulated by the target object along with its associated value and unique identifier.
RemoveAllMappingConstraints
The RemoveAllMappingConstraints operation is invoked to remove all of the constraint-value pairs currently encapsulated by the target filter object. Upon completion, the target filter object will still exist but have no constraint-value pairs associated with it.
Destroy
The Destroy operation destroys the target filter object, invalidating its object reference.
Match
The Match operation is invoked on an object supporting the IMappingFilter interface in order to determine how some property value of a particular event supplied to the channel in the form of a CORBA::Any should be modified. The operation accepts an Any as input, which contains the event being evaluated. Upon invocation, the target mapping filter object begins applying the constraints it encapsulates in order according to each constraints associated value, starting with the constraint with the best associated value for the specific property the mapping filter object was designed to affect (e.g., the highest priority, the longest lifetime, etc.), and ending with the constraint with the worst associated value. Upon encountering a constraint which the input filterable data matches, the operation sets the output parameter contained in its signature to the value associated with the constraint, and sets the return value of the operation to TRUE. If the input filterable data satisfies none of the constraints encapsulated by the target mapping filter object, the return value of the operation is set to FALSE, and the output parameter is set to the value of the defaultValue attribute associated with the target mapping filter object. The act of determining whether or not a given filterable event data passes a given filter constraint is specific to the type of grammar in which the filter constraint is specified. Thus, this operation will need to be re-implemented for each supported grammar.
If the input parameter contains data that the Match operation is not designed to handle, the UnsupportedFilterableData exception will be raised. An example of this would be if the filterable data contained a field whose name corresponds to a standard event field that has a numeric value, but the actual value associated with this field name within the event is a string.
MatchStructured
The MatchStructured operation is invoked on an object supporting the IMappingFilter interface in order to determine how some property value of a particular event supplied to the channel in the form of a Structured Event should be modified. The operation accepts a IMSNotification::StructuredEvent as input, which contains the event being evaluated. Upon invocation, the target mapping filter object begins applying the constraints it encapsulates in order according to each constraints associated value, starting with the constraint with the best associated value for the specific property the mapping filter object was designed to affect (e.g., the highest priority, the longest lifetime, etc.), and ending with the constraint with the worst associated value. Upon encountering a constraint which the input filterable data matches, the operation sets the output parameter contained in its signature to the value associated with the constraint, and sets the return value of the operation to TRUE. If the input filterable data satisfies none of the constraints encapsulated by the target mapping filter object, the return value of the operation is set to FALSE, and the output parameter is set to the value of the default_value attribute associated with the target mapping filter object. The act of determining whether or not a given filterable event data passes a given filter constraint is specific to the type of grammar in which the filter constraint is specified. Thus, this operation will need to be re-implemented for each supported grammar. If the input parameter contains data that the match operation is not designed to handle, the UnsupportedFilterableData exception will be raised. An example of this would be if the filterable data contained a field whose name corresponds to a standard event field that has a numeric value, but the actual value associated with this field name within the event is a string.
MatchTyped
The MatchTyped operation is invoked on an object supporting the IMappingFilter interface in order to determine how some property value of a particular event supplied to the channel in the form of a typed event should be modified. The operation accepts as input a sequence of name-value pairs which contains the contents of the event to be evaluated (how a typed event is converted to a sequence of name-value pairs by the channel is described in section 2.7). Upon invocation, the target mapping filter object begins applying the constraints it encapsulates in order according to each constraints associated value, starting with the constraint with the best associated value for the specific property the mapping filter object was designed to affect (e.g., the highest priority, the longest lifetime, etc.), and ending with the constraint with the worst associated value. Upon encountering a constraint which the input filterable data matches, the operation sets the output parameter contained in its signature to the value associated with the constraint, and sets the return value of the operation to TRUE. If the input filterable data satisfies none of the constraints encapsulated by the target mapping filter object, the return value of the operation is set to FALSE, and the output parameter is set to the value of the default_value attribute associated with the target mapping filter object. The act of determining whether or not a given filterable event data passes a given filter constraint is specific to the type of grammar in which the filter constraint is specified. Thus, this operation will need to be re-implemented for each supported grammar.
If the input parameter contains data that the Match operation is not designed to handle, the UnsupportedFilterableData exception will be raised. An example of this would be if the filterable data contained a field whose name corresponds to a standard event field that has a numeric value, but the actual value associated with this field name within the event is a string.
The IFilterFactory Interface
The IFilterFactory interface defines operations for creating filter objects.
CreateFilter
The CreateFilter operation is responsible for creating a new forwarding filter object. It takes as input a string parameter which identifies the grammar in which constraints associated with this filter will have meaning. If the client invoking this operation supplies as input the name of a grammar that is not supported by any forwarding filter implementation this factory is capable of creating, the InvalidGrammar exception is raised. Otherwise, the operation returns the reference to an object supporting the IFilter interface, which can subsequently be configured to support constraints in the appropriate grammar.
CreateMappingFilter
The CreateMappingFilter operation is responsible for creating a new mapping filter object. It takes as input a string parameter which identifies the grammar in which constraints associated with this filter will have meaning, and an Any which will be set as the defaultValue of the newly created mapping filter. If the client invoking this operation supplies as input the name of a grammar that is not supported by any mapping filter implementation this factory is capable of creating, the InvalidGrammar exception is raised. Otherwise, the operation returns the reference to an object supporting the IMappingFilter interface, which can subsequently be configured to support constraints in the appropriate grammar, along with their associated mapping values.
The IFilterAdmin Interface
The IFilterAdmin interface defines operations that enable an object supporting this interface to manage a list of filter objects, each of which supports the IFilter interface. This interface is intended to be an abstract interface which is inherited by all of the Proxy and Admin interfaces defined by the Notification Service. The difference in the semantics between a list of filter objects that is associated with an Admin object, and a list that is associated with a Proxy object, is described in section 2.1.2.
AddFilter
The AddFilter operation accepts as input the reference to an object supporting the IFilter interface. The affect of this operation is that the input filter object is appended to the list of filter objects associated with the target object upon which the operation was invoked. The operation associates with the newly added filter object a numeric identifier that is unique among all filter objects currently associated with the target, and returns that value as the result of the operation.
RemoveFilter
The RemoveFilter operation accepts as input a numeric value that is intended to be the unique identifier of a filter object that is currently associated with the target object. If identifier supplied does correspond to a filter object currently associated with the target object, then the corresponding filter object will be removed from the list of filters associated with the target object. Otherwise, the FilterNotFound exception will be raised.
GetFilter
The GetFilter operation accepts as input a numeric identifier that is intended to correspond to one of the filter objects currently associated with the target object. If this is the case, the object reference of the corresponding filter object is returned. Otherwise, the FilterNotFound exception is raised.
GetAllFilters
The GetAllFilters operation accepts no input parameters, and returns the list of unique identifiers which correspond to all of the filters currently associated with the target object.
RemoveAllFilters
The RemoveAllFilters operation accepts no input parameters, and removes all filter objects from the list of those currently associated with the target object.
The IMSNotifyComm Module
The IMSNotifyComm module defines the interfaces which support Notification Service clients that communicate using Structured Events or sequences of Structured Events. In addition, this module defines the interfaces which enable event suppliers to be informed when the types of events being subscribed to by their associated consumers change, and event consumers to be informed whenever there is a change in the types of events being produced by their suppliers (this model is described in detail in section 2.6).
The INotifyPublish Interface
The INotifyPublish interface supports an operation which allows a supplier of Notifications to announce, or publish, the names of the types of events it will be supplying, It is intended to be an abstract interface which is inherited by all Notification Service consumer interfaces, and enables suppliers to inform consumers supporting this interface of the types of events they intend to supply.
OfferChange
The OfferChange operation takes as input two sequences of event type names: the first specifying those event types which the client of the operation (an event supplier) is informing the target consumer object that it is adding to the list of event types it plans to supply, and the second specifying those event types which the client no longer plans to supply. This operation raises the InvalidEventType exception if one of the event type names supplied in either input parameter is syntactically invalid. In this case, the invalid name is returned in the type field of the exception.
Note that each event type name is comprised of two components: the name of the domain in which the event type has meaning, and the name of the actual event type. Also note that either component of a type name may specify a complete domain/event type name, a domain/event type name containing the wildcard * character, or the special event type name %ALL described in section 2.6.5.
The INotifySubscribe Interface
The INotifySubscribe interface supports an operation which allows a consumer of notifications to inform suppliers of notifications of the types of notifications it wishes to receive. It is intended to be an abstract interface which is inherited by all Notification Service supplier interfaces. In essence, its main purpose is to enable notification consumers to inform suppliers of the types of notifications that are of interest to them, ultimately enabling the suppliers to avoid supplying notifications that are not of interest to any consumer.
SubscriptionChange
The SubscriptionChange operation takes as input two sequences of event type names: the first specifying those event types which the associated Consumer wants to add to its subscription list, and the second specifying those event types which the associated consumer wants to remove from its subscription list. This operation raises the InvalidEventType exception if one of the event type names supplied in either input parameter is syntactically invalid. If this case, the invalid name is returned in the type field of the exception.
Note that each event type name is comprised of two components: the name of the domain in which the event type has meaning, and the name of the actual event type. Also note that either component of a type name may specify a complete domain/event type name, a domain/event type name containing the wildcard * character, or the special event type name %ALL described in section 2.6.5.
The ITxnPushConsumer Interface
The ITxnPushConsumer interface extends the IMSEventComm::IPushConsumer interface to provide support for standard Event Service events under transaction control using the push model. In addition, the ITxnPushConsumer interface inherits the INotifyPublish interface described above, enabling a notification supplier to inform an instance supporting this interface whenever there is a change to the types of events it intends to produce.
The ITxnPushConsumer interface provides transactional support for events using the CORBA Transaction Service (OTS). This enables the ability to treat a push consumer of events in the form of Anys as an OTS Recoverable Server or an XA Resource Manager. When transaction support is implemented, events pushed to such a consumer are available for usage by the consumer when the channel issues a successful OTS commit. If the transmission fails for any reason, the transaction is rolled back and these events should be discarded by the consumer, as opposed to actually being consumed. This is important in order to guarantee a consistent state of the application, since other effects of the same transaction (e.g., database changes) will also be undone.
The ITxnPullSupplier Interface
The ITxnPullSupplier interface extends the IMSEventComm::IPullSupplier interface to provide support for standard Event Service events under transaction control using the pull model. In addition, the ITxnPullSupplier interface inherits the INotifySubscribe interface described above, enabling a notification consumer to inform an instance supporting this interface whenever there is a change to the types of events it is interested in receiving.
The ITxnPullSupplier interface provides transactional support for pull style suppliers of Any events using the CORBA Transaction Service (OTS). This enables the ability to treat a pull style supplier as an OTS Recoverable Server or an XA Resource Manager. When transaction support is implemented, events are pulled by the channel within the context of a transaction. If the transmission fails for any reason, the transaction will be rolled back, and the channel discards any portion of the event(s) it has received. In this case, the supplier should also restore any state necessary such as to indicate it had not sent the event(s), since other effects of the same transaction (e.g., database changes) will also be undone.
The IStructuredPushConsumer Interface
The IStructuredPushConsumer interface supports an operation which enables consumers to receive Structured Events by the push model. It also defines an operation which can be invoked to disconnect the push consumer from its associated supplier. In addition, the IStructuredPushConsumer interface inherits the INotifyPublish interface described above, enabling a notification supplier to inform an instance supporting this interface whenever there is a change to the types of events it intends to produce. Note that an object supporting the IStructuredPushConsumer interface can receive all events which were supplied to its associated channel, including events supplied in a form other than a Structured Event. How events supplied to the channel in other forms are internally mapped into a Structured Event for delivery to a IStructuredPushConsumer is summarized in Table 2-2.
PushStructuredEvent
The PushStructuredEvent operation takes as input a parameter of type IStructuredEvent as defined in the IMSNotification module. Upon invocation, this parameter will contain an instance of a Structured Event being delivered to the consumer by the supplier to which it is connected. If this operation is invoked upon a IStructuredPushConsumer instance that is not currently connected to the supplier of the event, the Disconnected exception will be raised.
In reality there are two types of objects that will support the IStructuredPushConsumer interface: an object representing an application which receives Structured Events, and a IStructuredProxyPushConsumer (defined in the IMSNotifyChannelAdmin module) associated with an event channel which receives structured events from a supplier on behalf of the channel. For the first type of object, the implementation of the PushStructuredEvent operation is application specific, and is intended to be supplied by application developers. For the second type of object, the behavior of the operation is tightly linked to the implementation of the event channel. Basically, it is responsible for applying any filters that have been registered by with the StructuredProxyPushConsumer, then either discarding the event or forwarding it to each proxy supplier within the channel depending on whether or not the event passed the filter.
DisconnectStructuredPushConsumer
The DisconnectStructuredPushConsumer operation is invoked to terminate a connection between the target StructuredPushConsumer, and its associated supplier. This operation takes no input parameters and returns no values. The result of this operation is that the target StructuredPushConsumer will release all resources it had allocated to support the connection, and dispose its own object reference.
The ITxnStructuredPushConsumer Interface
The ITxnStructuredPushConsumer interface extends the IStructuredPushConsumer interface to provide transactional support for push style consumers of Structured Events using the CORBA Transaction Service (OTS). This enables the ability to treat such consumers as an OTS Recoverable Server or an XA Resource Manager. When transaction support is implemented, events pushed to such a consumer are available for usage by the consumer when the channel issues a successful OTS commit. If the transmission fails for any reason, the transaction is rolled back and these events should be discarded by the consumer, as opposed to actually being consumed. This is important in order to guarantee a consistent state of the application, since other effects of the same transaction (e.g., database changes) will also be undone.
The IStructuredPullConsumer Interface
The IStructuredPullConsumer interface supports the behavior of objects that receive Structured Events using pull-style communication. It defines an operation which can be invoked to disconnect the pull consumer from its associated supplier. In addition, the IStructuredPullConsumer interface inherits the INotifyPublish interface described above, enabling a notification supplier to inform an instance supporting this interface whenever there is a change to the types of events it intends to produce.
Note that an object supporting the IStructuredPullConsumer interface can receive all events which were supplied to its associated channel, including events supplied in a form other than a Structured Event. How events supplied to the channel in other forms are internally mapped into a Structured Event for delivery to a StructuredPullConsumer is summarized in Table 2-2.
DisconnectStructuredPullConsumer
The DisconnectStructuredPullConsumer operation is invoked to terminate a connection between the target StructuredPullConsumer, and its associated supplier. This operation takes no input parameters and returns no values. The result of this operation is that the target StructuredPullConsumer will release all resources it had allocated to support the connection, and dispose its own object reference.
The IStructuredPullSupplier Interface
The IStructuredPullSupplier interface supports operations which enable suppliers to transmit Structured Events by the pull model. It also defines an operation which can be invoked to disconnect the pull supplier from its associated consumer. In addition, the IStructuredPullSupplier interface inherits the INotifySubscribe interface described above, enabling a notification consumer to inform an instance supporting this interface whenever there is a change to the types of events it is interested in receiving.
Note that an object supporting the IStructuredPullSupplier interface can transmit events which can potentially be received by any consumer connected to the channel, including those which consume events in a form other than a Structured Event. How events supplied to the channel in the form of a Structured Event are internally mapped into different forms for delivery to consumers which receive events in a form other than the Structured Event is summarized in Table 2-2.
PullStructuredEvent
The PullStructuredEvent operation takes no input parameters, and returns a value of type Structured Event as defined in the IMSNotification module. Upon invocation, the operation will block until an event is available for transmission, at which time it will return an instance of a Structured Event which contains the event being delivered to its connected consumer. If invoked upon a StructuredPullSupplier that is not currently connected to the consumer of the event, the Disconnected exception will be raised.
In reality there are two types of objects that will support the IStructuredPullSupplier interface: an object representing an application which transmits Structured Events, and a StructuredProxyPullSupplier (defined in the IMSNotifyChannelAdmin module) associated with an event channel which transmits events to a pull style consumer on behalf of the channel. For the first type of object, the implementation of the PullStructuredEvent operation is application specific, and is intended to be supplied by application developers. The application specific implementation of this operation should construct a structured event, and return it within a StructuredEvent data structure. For the second type of object, the behavior of the operation is tightly linked to the implementation of the event channel. Basically, it is responsible for forwardinga structured event, within an StructuredEvent data structure, as the return value to the consumer it is connected to upon the availability of an event which passes the filter(s) associated with the StructuredProxyPullSupplier. Note that the operation will block until such an event is available to return.
TryPullStructuredEvent
The TryPullStructuredEvent operation takes no input parameters, and returns a value of type StructuredEvent as defined in the IMSNotification module. It also returns an output parameter of type boolean which indicates whether or not the return value actually contains an event. Upon invocation, the operation will return an instance of a Structured Event which contains the event being delivered to its connected consumer, if such an event is available for delivery at the time the operation was invoked. If an event is available for delivery and thus returned as the result, the output parameter of the operation will be set to TRUE. If no event is available to return upon invocation, the operation will return immediately with the value of the output parameter set to FALSE. In this case, the return value will not contain a valid event. If invoked upon a StructuredPullSupplier that is not currently connected to the consumer of the event, the Disconnected exception will be raised.
In reality there are two types of objects that will support the IStructuredPullSupplier interface: an object representing an application which transmits Structured Events, and a IStructuredProxyPullSupplier (defined within the IMSNotifyChannelAdmin module) associated with an event channel which transmits events to a PullConsumer on behalf of the channel. For the first type of object, the implementation of the TryPullStructuredEvent operation is application specific, and is intended to be supplied by application developers. If an event is available to be returned upon invocation of this operation, the application specific implementation of this operation should construct a Structured Event, and return it within a StructuredEvent data structure along with setting the value of the output parameter to TRUE. Otherwise, the operation should return immediately after setting the value of the output parameter to FALSE. For the second type of object, the behavior of the operation is tightly linked to the implementation of the event channel. Basically, if an event is available to be returned upon invocation of this operation, it is responsible for forwarding it, within a StructuredEvent data structure, as the return value to the consumer it is connected to, in addition to setting the output parameter to FALSE. If no event is available to return to the consumer upon invocation of this operation, it will immediately return with the output parameter to set to FALSE, and the return value not containing a valid event.
DisconnectStructuredPullSupplier
The DisconnectStructuredPullSupplier operation is invoked to terminate a connection between the target StructuredPullSupplier, and its associated consumer. This operation takes no input parameters and returns no values. The result of this operation is that the target StructuredPullSupplier will release all resources it had allocated to support the connection, and dispose its own object reference.
The ITxnStructuredPullSupplier Interface
The ITxnStructuredPullSupplier interface extends the IStructuredPullSupplier interface to provide transactional support for pull style suppliers of Structured Events using the CORBA Transaction Service (OTS). This enables the ability to treat such a supplier as an OTS Recoverable Server or an XA Resource Manager. When transaction support is implemented, events are pulled by the channel within the context of a transaction. If the transmission fails for any reason, the transaction will be rolled back, and the channel discards any portion of the event(s) it has received. In this case, the supplier should also restore any state necessary such as to indicate it had not sent the event(s), since other effects of the same transaction (e.g., database changes) will also be undone.
The IStructuredPushSupplier Interface
The IStructuredPushSupplier interface supports the behavior of objects that transmit Structured Events using push-style communication. It defines an operation which can be invoked to disconnect the push supplier from its associated consumer. In addition, the IStructuredPushSupplier interface inherits the INotifySubscribe interface described above, enabling a notification consumer to inform an instance supporting this interface whenever there is a change to the types of events it is interested in receiving.
Note that an object supporting the IStructuredPushSupplier interface can transmit events which can potentially be received by any consumer connected to the channel, including those which consume events in a form other than a Structured Event. How events supplied to the channel in the form of a Structured Event are internally mapped into different forms for delivery to consumers which receive events in a form other than the Structured Event is summarized in Table 2-2.
DisconnectStructuredPushSupplier
The DisconnectStructuredPushSupplier operation is invoked to terminate a connection between the target StructuredPushSupplier, and its associated consumer. This operation takes no input parameters and returns no values. The result of this operation is that the target StructuredPushSupplier will release all resources it had allocated to support the connection, and dispose its own object reference.
The ISequencePushConsumer Interface
The ISequencePushConsumer interface supports an operation which enables consumers to receive sequences Structured Events by the push model. It also defines an operation which can be invoked to disconnect the push consumer from its associated supplier. In addition, the ISequencePushConsumer interface inherits the INotifyPublish interface described above, enabling a notification supplier to inform an instance supporting this interface whenever there is a change to the types of events it intends to produce.
Note that an object supporting the ISequencePushConsumer interface can receive all events which were supplied to its associated channel, including events supplied in a form other than a sequence of Structured Events. How events supplied to the channel in other forms are internally mapped into a sequence of Structured Events for delivery to a SequencePushConsumer is summarized in Table 2-2.
PushStructuredEvents
The PushStructuredEvents operation takes as input a parameter of type EventBatch as defined in the IMSNotification module. This data type is the same as a sequence of Structured Events. Upon invocation, this parameter will contain a sequence of Structured Events being delivered to the consumer by the supplier to which it is connected. If this operation is invoked upon a SequencePushConsumer instance that is not currently connected to the supplier of the event, the Disconnected exception will be raised.
Note that the maximum number of events that will be transmitted within a single invocation of this operation, along with the amount of time a supplier of a sequence of Structured Events will accumulate individual events into the sequence before invoking this operation, are controlled by QoS property settings. In reality there are two types of objects that will support the ISequencePushConsumer interface: an object representing an application which receives sequences of Structured Events, and a ISequenceProxyPushConsumer (defined in the IMSNotifyChannelAdmin module) associated with an event channel which receives sequences of Structured Events from a supplier on behalf of the channel. For the first type of object, the implementation of the PushStructuredEvents operation is application specific, and is intended to be supplied by application developers. For the second type of object, the behavior of the operation is tightly linked to the implementation of the event channel. Basically, it is responsible for applying any filters that have been registered by with the ISequenceProxyPushConsumer to each event in each sequence it receives, then either discarding each event or forwarding it to each proxy supplier within the channel depending on whether or not the event passed the filter.
DisconnectSequencePushConsumer
The DisconnectSequencePushConsumer operation is invoked to terminate a connection between the target SequencePushConsumer, and its associated supplier. This operation takes no input parameters and returns no values. The result of this operation is that the target SequencePushConsumer will release all resources it had allocated to support the connection, and dispose its own object reference.
The ITxnSequencePushConsumer Interface
The ITxnSequencePushConsumer interface extends the ISequencePushConsumer interface to provide transactional support for push style consumers of sequences of Structured Events using the CORBA Transaction Service (OTS). This enables the ability to treat such consumers as an OTS Recoverable Server or an XA Resource Manager. When transaction support is implemented, events pushed to such a consumer are available for usage by the consumer when the channel issues a successful OTS commit. If the transmission fails for any reason, the transaction is rolled back and these events should be discarded by the consumer, as opposed to actually being consumed. This is important in order to guarantee a consistent state of the application, since other effects of the same transaction (e.g., database changes) will also be undone.
The ISequencePullConsumer Interface
The ISequencePullConsumer interface supports the behavior of objects that receive sequences of Structured Events using pull-style communication. It defines an operation which can be invoked to disconnect the pull consumer from its associated supplier. In addition, the ISequencePullConsumer interface inherits the INotifyPublish interface described above, enabling a notification supplier to inform an instance supporting this interface whenever there is a change to the types of events it intends to produce. Note that an object supporting the ISequencePullConsumer interface can receive all events which were supplied to its associated channel, including events supplied in a form other than a sequence of Structured Events. How events supplied to the channel in other forms are internally mapped into a sequence of Structured Events for delivery to a SequencePullConsumer is summarized in Table 2-2.
DisconnectSequencePullConsumer
The DisconnectSequencePullConsumer operation is invoked to terminate a connection between the target SequencePullConsumer, and its associated supplier. This operation takes no input parameters and returns no values. The result of this operation is that the target SequencePullConsumer will release all resources it had allocated to support the connection, and dispose its own object reference.
The ISequencePullSupplier Interface
The ISequencePullSupplier interface supports operations which enable suppliers to transmit sequences of Structured Events by the pull model. It also defines an operation which can be invoked to disconnect the pull supplier from its associated consumer. In addition, the ISequencePullSupplier interface inherits the INotifySubscribe interface described above, enabling a notification consumer to inform an instance supporting this interface whenever there is a change to the types of events it is interested in receiving.
Note that an object supporting the ISequencePullSupplier interface can transmit events which can potentially be received by any consumer connected to the channel, including those which consume events in a form other than a sequence of Structured Events. How events supplied to the channel in the form of a sequence of Structured Events are internally mapped into different forms for delivery to consumers which receive events in a form other than the a sequence of Structured Events is summarized in Table 2-2.
PullStructuredEvents
The PullStructuredEvents operation takes as an input parameter a numeric value, and returns a value of type EventBatch as defined in the IMSNotification module. This data type is the same as a sequence of Structured Events. Upon invocation, the operation will block until a sequence of Structured Events is available for transmission, at which time it will return the sequence containing events being delivered to its connected consumer. If invoked upon a SequencePullSupplier that is not currently connected to the consumer of the event, the Disconnected exception will be raised.
Note that the maximum length of the sequence returned will never exceed the value of the input parameter. In addition, the amount of time the supplier will accumulate events into the sequence before transmitting it, along with the maximum size of any sequence it will transmit (regardless of the input parameter), are controlled by QoS property settings as described in section 2.5.5.
In reality there are two types of objects that will support the ISequencePullSupplier interface: an object representing an application which transmits sequences of Structured Events, and a ISequenceProxyPullSupplier (defined in the IMSNotifyChannelAdmin module) associated with an event channel which transmits events to a pull style consumer on behalf of the channel. For the first type of object, the implementation of the PullStructuredEvents operation is application specific, and is intended to be supplied by application developers. The application specific implementation of this operation should construct a sequence of Structured Events, and return it within a EventBatch data structure. For the second type of object, the behavior of the operation is tightly linked to the implementation of the event channel. Basically, it is responsible for forwarding a sequence of Structured Events, within an EventBatch data structure, as the return value to the consumer it is connected to upon the availability of events which pass the filter(s) associated with the SequenceProxyPullSupplier. Note that the operation will block until there is a sequence available to return.
TryPullStructuredEvents
The TryPullStructuredEvents operation takes as an input parameter a numeric value, and returns a value of type EventBatch as defined in the IMSNotification module. This data type is the same as a sequence of Structured Events. The operation also returns an output parameter of type boolean which indicates whether or not the return value actually contains a sequence of events. Upon invocation, the operation will return a sequence of a Structured Events which contains events being delivered to its connected consumer, if such a sequence is available for delivery at the time the operation was invoked. If an event sequence is available for delivery and thus returned as the result, the output parameter of the operation will be set to TRUE. If no event sequence is available to return upon invocation, the operation will return immediately with the value of the output parameter set to FALSE. In this case, the return value will not contain a valid event sequence. If invoked upon a SequencePullSupplier that is not currently connected to the consumer of the event, the Disconnected exception will be raised.
Note that the maximum length of the sequence returned will never exceed the value ofthe input parameter.
In reality there are two types of objects that will support the ISequencePullSupplier interface: an object representing an application which transmits sequences of Structured Events, and a ISequenceProxyPullSupplier (defined within the IMSNotifyChannelAdmin module) associated with an event channel which transmits events to a PullConsumer on behalf of the channel. For the first type of object, the implementation of the TryPullStructuredEvents operation is application specific, and is intended to be supplied by application developers. If an event sequence is available to be returned upon invocation of this operation, the application specific implementation of this operation should construct an EventBatch instance, and return it along with setting the value of the output parameter to TRUE. Otherwise, the operation should return immediately after setting the value of the output parameter to FALSE. For the second type of object, the behavior of the operation is tightly linked to the implementation of the event channel. Basically, if an event sequence is available to be returned upon invocation of this operation, it is responsible for forwarding it, within an EventBatch data structure, as the return value to the consumer it is connected to, in addition to setting the output parameter to FALSE. If no event sequence is available to return to the consumer upon invocation of this operation, it will immediately return with the output parameter to set to FALSE, and the return value not containing a valid event.
DisconnectSequencePullSupplier
The DisconnectSequencePullSupplier operation is invoked to terminate a connection between the target SequencePullSupplier, and its associated consumer. This operation takes no input parameters and returns no values. The result of this operation is that the target SequencePullSupplier will release all resources it had allocated to support the connection, and dispose its own object reference.
The ITxnSequencePullSupplier Interface
The ITxnSequencePullSupplier interface extends the ISequencePullSupplier interface to provide transactional support for pull style suppliers of sequences of Structured Events using the CORBA Transaction Service (OTS). This enables the ability to treat such a supplier as an OTS Recoverable Server or an XA Resource Manager. When transaction support is implemented, events are pulled by the channel within the context of a transaction. If the transmission fails for any reason, the transaction will be rolled back, and the channel discards any portion of the event(s) it has received. In this case, the supplier should also restore any state necessary such as to indicate it had not sent the event(s), since other effects of the same transaction (e.g., database changes) will also be undone.
The ISequencePushSupplier Interface
The ISequencePushSupplier interface supports the behavior of objects that transmit sequences of Structured Events using push-style communication. It defines an operation which can be invoked to disconnect the push supplier from its associated consumer. In addition, the ISequencePushSupplier interface inherits the INotifySubscribe interface described above, enabling a notification consumer to inform an instance supporting this interface whenever there is a change to the types of events it is interested in receiving.
Note that an object supporting the ISequencePushSupplier interface can transmit events which can potentially be received by any consumer connected to the channel, including those which consume events in a form other than a sequence of Structured Events. How events supplied to the channel in the form of a sequence of Structured Events are internally mapped into different forms for delivery to consumers which receive events in a form other than a sequence of Structured Events is summarized in Table 2-2.
DisconnectSequencePushSupplier
The DisconnectSequencePushSupplier operation is invoked to terminate a connection between the target SequencePushSupplier, and its associated consumer. This operation takes no input parameters and returns no values. The result of this operation is that the target SequencePushSupplier will release all resources it had allocated to support the connection, and dispose its own object reference.
The IMSNotifyChannelAdmin Module
The IMSNotifyChannelAdmin module defines the interfaces necessary to create, configure, and administer instances of a Notification Service event channel. It defines the different types of proxy interfaces which support connections from the various types of clients that are supported, the Admin interfaces, the EventChannel interface, and a factory interface for instantiating new channels.
The IProxyConsumer Interface
The IProxyConsumer interface is intended to be an abstract interface that is inherited by the different varieties of proxy consumers that can be instantiated within a notification channel. It encapsulates the behaviors common to all Notification Service proxy consumers. In particular, the IProxyConsumer interface inherits the IQoSAdmin interface defined within the IMSNotification module, and the IFilterAdmin interface defined within the IMSNotifyFilter module. The former inheritance enables all proxy consumers to administer a list of associated QoS properties, while the latter inheritance enables all proxy consumers to administer a list of associated filter objects. Locally, the IProxyConsumer interface defines a readonly attribute which contains a reference to the ISupplierAdmin object that created it. In addition, the IProxyConsumer interface defines an operation that returns the list of event types a given proxy consumer instance is configured to forward, and an operation which can be queried to determine which message level QoS properties can be set on a per-event basis.
ObtainSubscriptionTypes
The ObtainSubscriptionTypes operation accepts no parameters and returns a list of event type names. This returned list represents the names of event types which consumers connected to the channel are interested in receiving. Consumers express their interest in receiving particular types of events by configuring filters associated with the proxy suppliers to which they are connected to encapsulate constraints which express subscriptions to specific event instances. Such subscriptions could be based on the types and/or contents of events. The proxy suppliers extract the event type information from these subscriptions, and share it with the proxy consumer objects connected to the same channel. Supplier objects can thus obtain this information from the channel by invoking the ObtainSubscriptionTypes operation on the proxy consumer object to which they are connected. This information enables suppliers to suppress sending types of events to the channel in which no consumer is currently interested.
ValidateEventQos
The ValidateEventQos operation accepts as input a sequence of QoS property name-value pairs which specify a set of QoS settings that a client is interested in setting on a per-event basis. Note that the QoS property settings contained in the optional header fields of a Structured Event may differ from those that are configured on a given proxy object. This operation is essentially a check to see if the target proxy object will honor the setting of a set of QoS properties on a per-event basis to values that may conflict with those set on the proxy itself. If any of the requested settings would not be honored by the target object on a per-event basis, the operation raises the UnsupportedQoS exception. This exception contains as data a sequence of data structures, each of which identifies the name of a QoS property in the input list whose requested setting could not be satisfied, along with an error code and a range of settings for the property which could be satisfied. The meanings of the error codes which might be returned are described in Table 2-4.
If all requested QoS property value settings could be satisfied by the target object, the operation returns successfully with an output parameter that contains a sequence of PropertyRange data structures. Each element in this sequence includes the name of a an additional QoS property whose setting is supported by the target object on a per-event basis and which could have been included on the input list while still resulting in a successful return from the operation. Each element also includes the range of values that would have been acceptable for each such property.
The IProxySupplier Interface
The IProxySupplier interface is intended to be an abstract interface that is inherited by the different varieties of proxy suppliers that can be instantiated within a notification channel. It encapsulates the behaviors common to all Notification Service proxy suppliers. In particular, the IProxySupplier interface inherits the IQoSAdmin interface defined within the IMSNotification module, and the IFilterAdmin interface defined within the IMSNotifyFilter module. The former inheritance enables all proxy suppliers to administer a list of associated QoS properties, while the latter inheritance enables all proxy suppliers to administer a list of associated filter objects. Locally, the IProxySupplier interface defines a readonly attribute which contains a reference to the IConsumerAdmin object that created it. In addition, the ProxySupplier interface defines attributes that associate with each proxy supplier two mapping filter objects, one for priority and one for lifetime. As described in section 2.3.1, these mapping filter objects enable proxy suppliers to be configured to alter the way they treat events with respect to their priority and lifetime based on the type and contents of each individual event. Lastly, the IProxySupplier interface defines an operation that returns the list of event types that a given proxy supplier could potentially forward to its associated consumer, and an operation which can be queried to determine which message level QoS properties can be set on a per-event basis.
priorityFilter
The PriorityFilter attribute contains a reference to an object supporting the IMappingFilter interface defined in the IMSNotifyFilter module. Such an object encapsulates a list of constraint-value pairs, where each constraint is a boolean expression based on the type and contents of an event, and the value is a possible priority setting for the event. Upon receipt of each event by a proxy supplier object whose PriorityFilter attribute contains a non-nil reference, the proxy supplier will invoke the appropriate variant of the Match operation supported by the mapping filter object. The mapping filter object will proceed to apply its encapsulated constraints to the event, and return the one with the highest associated priority setting which evaluates to TRUE, or else its associated defaultValue if no constraints evaluate to TRUE. Upon return from the Match operation, if the output parameter is TRUE, the proxy supplier treats the event with respect to its priority according to the return value, as opposed to a priority setting contained within the event. If the output parameter is FALSE, the proxy supplier will treat the event with respect to its priority according to the value set for the priority property in the event header if this property is present, otherwise it will use the output parameter returned from the Match operation (i.e., the default value of the mapping filter object).
lifetimeFilter
The lifetime_filter attribute contains a reference to an object supporting the IMappingFilter interface defined in the IMSNotifyFilter module. Such an object encapsulates a list of constraint-value pairs, where each constraint is a boolean expression based on the type and contents of an event, and the value is a possible lifetime setting for the event. Upon receipt of each event by a proxy supplier object whose lifetimeFilter attribute contains a non-nil reference, the proxy supplier will invoke the appropriate variant of the Match operation supported by the mapping filter object. The mapping filter object will proceed to apply its encapsulated constraints to the event, and return the one with the highest associated lifetime setting which evaluates to TRUE, or else its associated defaultValue if no constraints evaluate to TRUE. Upon return from the Match operation, if the output parameter is TRUE, the proxy supplier treats the event with respect to its lifetime according to the return value, as opposed to a lifetime setting contained within the event. If the output parameter is FALSE, the proxy supplier will treat the event with respect to its lifetime according to the value set for the lifetime property in the event header if this property is present, otherwise it will use the output parameter returned from the Match operation (i.e., the default value of the mapping filter object).
ObtainOfferedTypes
The ObtainOfferedTypes operation accepts no parameters and returns a list of event type names. Each element of the returned list names a type of event that the target proxy supplier object could potentially forward to its associated consumer. Note that through inheritance, all proxy consumer objects will support the INotifyPublish interface defined in the IMSNotifyComm module. This interface supports the OfferChange operation, which can be invoked by suppliers each time there is a change to the list of event types they plan to supply to their associated consumer. Thus, this mechanism relies on event suppliers keeping the channel informed of the types of events they plan to supply by invoking the OfferChange operation on their associated proxy consumer object. Internally to the channel, the proxy consumers will share the information about event types that will be supplied to the channel with the proxy supplier objects associated with the channel. This enables consumers to discover the types of events that could by supplied to them by the channel by invoking the ObtainOfferedTypes operation on their associated proxy supplier.
ValidateEventQos
The ValidateEventQos operation accepts as input a sequence of QoS property name-value pairs which specify a set of QoS settings that a client is interested in setting on a per-event basis. Note that the QoS property settings contained in the optional header fields of a Structured Event may differ from those that are configured on a given proxy object. This operation is essentially a check to see if the target proxy object will honor the setting of a set of QoS properties on a per-event basis to values that may conflict with those set on the proxy itself. If any of the requested settings would not be honored by the target object on a per-event basis, the operation raises the UnsupportedQoS exception. This exception contains as data a sequence of data structures, each of which identifies the name of a QoS property in the input list whose requested setting could not be satisfied, along with an error code and a range of settings for the property which could be satisfied. The meanings of the error codes which might be returned are described in Table 2-4.
If all requested QoS property value settings could be satisfied by the target object, the operation returns successfully with an output parameter that contains a sequence of PropertyRange data structures. Each element in this sequence includes the name of a an additional QoS property whose setting is supported by the target object on a per-event basis and which could have been included on the input list while still resulting in a successful return from the operation. Each element also includes the range of values that would have been acceptable for each such property.
The IProxyPushConsumer Interface
The IProxyPushConsumer interface supports connections to the channel by suppliers who will push events to the channel as untyped Anys. Note that such suppliers are identical to OMG Event Service push-style suppliers of untyped events. The IProxyPushConsumer interface defined here, however, supports event filtering and configuration of various QoS properties. Thus, this interface enables OMG Event Service style untyped event suppliers to take advantage of these new features offered by the Notification Service.
Through inheritance of the IProxyConsumer interface, the IProxyPushConsumer interface supports administration of various QoS properties, administration of a list of associated filter objects, and a readonly attribute containing the reference of the ISupplierAdmin object which created it. In addition, this inheritance implies that a IProxyPushConsumer instance supports an operation which will return the list of event types which consumers connected to the same channel are interested in receiving, and an operation which can return information about the instances ability to accept a per-event QoS request.
The IProxyPushConsumer interface inherits the INotifyPublish interface defined in the IMSNotifyComm module, enabling its associated supplier to inform it whenever the list of event types which the supplier plans to supply changes.
The IProxyPushConsumer interface also inherits from the IPushConsumer interface defined within the IMSEventComm module of the OMG Event Service. This interface supports the Pull operation which the supplier connected to a IProxyPushConsumer instance will invoke to send an event to the channel in the form of an Any, and the operation required to disconnect the IProxyPushConsumer from its associated supplier. Finally, the IProxyPushConsumer interface defines the operation which can be invoked by a push supplier to establish the connection over which the push supplier will send events to the channel.
ConnectAnyPushSupplier
The ConnectAnyPushSupplier operation accepts as an input parameter the reference to an object supporting the IPushSupplier interface defined within the IMSEventComm module of the OMG Event Service. This reference is that of a supplier which plans to push events to the channel with which the target object is associated in the form of untyped Anys. This operation is thus invoked in order to establish a connection between a push-style supplier of events in the form of Anys, and the notification channel. Once established, the supplier can proceed to send events to the channel by invoking the push operation supported by the target IProxyPushConsumer instance. If the target object of this operation is already connected to a push supplier object, the AlreadyConnected exception will be raised.
The ITxnProxyPushConsumer Interface
The ITxnProxyPushConsumer interface supports connections to the channel by suppliers who will push events to the channel as untyped anys. It adds transactional behavior of these events to the functions provided in the IProxyPushConsumer interface. Events pushed to the channel within the context of a transaction do not logically enter the channel until the supplier commits the transaction. If the supplier aborts the transaction, any event(s) it had supplied are thus discarded by the channel, and the channel proceeds to behave as if it had never received these events.
The IStructuredProxyPushConsumer Interface
The IStructuredProxyPushConsumer interface supports connections to the channel by suppliers who will push events to the channel as Structured Events. Through inheritance of the IProxyConsumer interface, the IStructuredProxyPushConsumer interface supports administration of various QoS properties, administration of a list of associated filter objects, and a readonly attribute containing the reference of the ISupplierAdmin object which created it. In addition, this inheritance implies that a IStructuredProxyPushConsumer instance supports an operation which will return the list of event types which consumers connected to the same channel are interested in receiving, and an operation which can return information about the instances ability to accept a per-event QoS request.
The IStructuredProxyPushConsumer interface also inherits from the IStructuredPushConsumer interface defined in the IMSNotifyComm module. This interface supports the operation which enables a supplier of Structured Events to push them to the IStructuredProxyPushConumer, and also the operation which can be invoked to close down the connection from the supplier to the IStructuredProxyPushConsumer. In addition, since the IStructuredPushConsumer interface inherits from the INotifyPublish interface, a supplier can inform the IStructuredProxyPushConsumer to which it is connected whenever the list of event types it plans to supply to the channel changes.
Lastly, the IStructuredProxyPushConsumer interface defines a method that can be invoked by a push-style supplier of Structured Events in order to establish a connection between the supplier and a notification channel over which the supplier will proceed to send events.
ConnectStructuredPushSupplier
The ConnectStructuredPushSupplier operation accepts as an input parameter the reference to an object supporting the IStructuredPushSupplier interface defined within the IMSNotifyComm module. This reference is that of a supplier which plans to push events to the channel with which the target object is associated in the form of Structured Events. This operation is thus invoked in order to establish a connection between a push-style supplier of events in the form of Structured Events, and the notification channel. Once established, the supplier can proceed to send events to the channel by invoking the PushStructuredEvent operation supported by the target IStructuredProxyPushConsumer instance. If the target object of this operation is already connected to a push supplier object, the AlreadyConnected exception will be raised.
The ITxnStructuredProxyPushConsumer Interface
The ITxnStructuredProxyPushConsumer interface supports connections to the channel by suppliers who will push events to the channel as Structured Events. It adds transactional behavior of these events to the functions provided in the IStructuredProxyPushConsumer interface. Events pushed to the channel within the context of a transaction do not logically enter the channel until the supplier commits the transaction. If the supplier aborts the transaction, any event(s) it had supplied are thus discarded by the channel, and the channel proceeds to behave as if it had never received these events.
The ISequenceProxyPushConsumer Interface
The ISequenceProxyPushConsumer interface supports connections to the channel by suppliers who will push events to the channel as sequences of Structured Events. Through inheritance of the IProxyConsumer interface, the ISequenceProxyPushConsumer interface supports administration of various QoS properties, administration of a list of associated filter objects, and a readonly attribute containing the reference of the ISupplierAdmin object which created it. In addition, this inheritance implies that a ISequenceProxyPushConsumer instance supports an operation which will return the list of event types which consumers connected to the same channel are interested in receiving, and an operation which can return information about the instances ability to accept a per-event QoS request.
The ISequenceProxyPushConsumer interface also inherits from the ISequencePushConsumer interface defined in the IMSNotifyComm module. This interface supports the operation which enables a supplier of sequences of Structured Events to push them to the ISequenceProxyPushConumer, and also the operation which can be invoked to close down the connection from the supplier to the ISequenceProxyPushConsumer. In addition, since the ISequencePushConsumer interface inherits from the INotifyPublish interface, a supplier can inform the ISequenceProxyPushConsumer to which it is connected whenever the list of event types it plans to supply to the channel changes.
Lastly, the ISequenceProxyPushConsumer interface defines a method that can be invoked by a push-style supplier of sequences of Structured Events in order to establish a connection between the supplier and a notification channel over which the supplier will proceed to send events.
ConnectSequencePushSupplier
The ConnectSequencePushSupplier operation accepts as an input parameter the reference to an object supporting the ISequencePushSupplier interface defined within the IMSNotifyComm module. This reference is that of a supplier which plans to push events to the channel with which the target object is associated in the form of sequences of Structured Events. This operation is thus invoked in order to establish a connection between a push-style supplier of events in the form of sequences of Structured Events, and the notification channel. Once established, the supplier can proceed to send events to the channel by invoking the PushStructuredEvents operation supported by the target ISequenceProxyPushConsumer instance. If the target object of this operation is already connected to a push supplier object, the AlreadyConnected exception will be raised.
The ITxnSequenceProxyPushConsumer Interface
The ITxnSequenceProxyPushConsumer interface supports connections to the channel by suppliers who will push events to the channel as a sequence of Structured Events. It adds transactional behavior of these events to the functions provided in the ISequenceProxyPushConsumer interface. Events pushed to the channel within the context of a transaction do not logically enter the channel until the supplier commits the transaction. If the supplier aborts the transaction, any event(s) it had supplied are thus discarded by the channel, and the channel proceeds to behave as if it had never received these events.
The IProxyPullSupplier Interface
The IProxyPullSupplier interface supports connections to the channel by consumers who will pull events from the channel as untyped Anys. Note that such consumers are identical to OMG Event Service pull-style consumers of untyped events. The IProxyPullSupplier interface defined here, however, supports event filtering and configuration of various QoS properties. Thus, this interface enables OMG Event Service style untyped event consumers to take advantage of these new features offered by the Notification Service.
Through inheritance of the IProxySupplier interface, the IProxyPullSupplier interface supports administration of various QoS properties, administration of a list of associated filter objects, mapping filters for event priority and lifetime, and a readonly attribute containing the reference of the IConsumerAdmin object which created it. In addition, this inheritance implies that a IProxyPullSupplier instance supports an operation which will return the list of event types which the proxy supplier will potentially by supplying, and an operation which can return information about the instances ability to accept a per-event QoS request.
The IProxyPullSupplier interface inherits the INotifySubscribe interface defined in the IIMSNotifyComm module, enabling it to be notified whenever its associated consumer changes the list of event types it is interested in receiving. This notification occurs via the callback mechanism described in section 2.3.
The IProxyPullSupplier interface also inherits from the IPullSupplier interface defined within the IMSEventComm module of the OMG Event Service. This interface supports the pull and try_pull operations which the consumer connected to a IProxyPullSupplier instance will invoke to receive an event from the channel in the form of an Any, and the operation required to disconnect the IProxyPullSupplier from its associated consumer. Finally, the IProxyPullSupplier interface defines the operation which can be invoked by a pull consumer to establish the connection over which the pull consumer will receive events from the channel.
ConnectAnyPullConsumer
The ConnectAnyPullConsumer operation accepts as an input parameter the reference to an object supporting the IPullConsumer interface defined within the IMSEventComm module of the OMG Event Service. This reference is that of a consumer which plans to pull events from the channel with which the target object is associated in the form of untyped Anys. This operation is thus invoked in order to establish a connection between a pull-style consumer of events in the form of Anys, and the notification channel. Once established, the consumer can proceed to receive events from the channel by invoking the Pull or TryPull operations supported by the target IProxyPullSupplier instance. If the target object of this operation is already connected to a pull consumer object, the AlreadyConnected exception will be raised.
The ITxnProxyPullSupplier Interface
The ITxnProxyPullSupplier interface supports connections to the channel by consumers who will pull events from the channel as untyped anys. It adds transactional behavior of these events to the functions provided in the IProxyPullSupplier interface. Events pulled from the channel within the context of a transaction are not deleted from a proxy suppliers queue until the consumer performing the pull operation(s) commits the transaction. If the transaction aborts, the channel treats the event(s) as if they had not been pulled from the proxy supplier involved in the transaction. In this case, the application should discard any portion of the event(s) it had received during the transaction, as other effects of the transaction (e.g., database updates) will also be undone.
The IStructuredProxyPullSupplier Interface
The IStructuredProxyPullSupplier interface supports connections to the channel by consumers who will pull events from the channel as Structured Events. Through inheritance of the IProxySupplier interface, the IStructuredProxyPullSupplier interface supports administration of various QoS properties, administration of a list of associated filter objects, and a readonly attribute containing the reference of the IConsumerAdmin object which created it. In addition, this inheritance implies that a IStructuredProxyPullSupplier instance supports an operation which will return the list of event types which the proxy supplier will potentially by supplying, and an operation which can return information about the instances ability to accept a per-event QoS request.
The IStructuredProxyPullSupplier interface also inherits from the IStructuredPullSupplier interface defined in the IMSNotifyComm module. This interface supports the operations which enable a consumer of Structured Events to pull them from the IStructuredProxyPullSupplier, and also the operation which can be invoked to close down the connection from the consumer to the IStructuredProxyPullSupplier. In addition, since the IStructuredPullSupplier interface inherits from the INotifySubscribe interface, a IStructuredProxyPullSupplier can be notified whenever the list of event types which its associated consumer is interested in receiving changes. This notification occurs via the callback mechanism described in section 2.3.
Lastly, the IStructuredProxyPullSupplier interface defines a method that can be invoked by a pull-style consumer of Structured Events in order to establish a connection between the consumer and a notification channel over which the consumer will proceed to receive events.
ConnectStructuredPullConsumer
The ConnectStructuredPullConsumer operation accepts as an input parameter the reference to an object supporting the IStructuredPullConsumer interface defined within the IMSNotifyComm module. This reference is that of a consumer which plans to pull events from the channel to which the target object is associated in the form of Structured Events. This operation is thus invoked in order to establish a connection between a pull-style consumer of events in the form of Structured Events, and the notification channel. Once established, the consumer can proceed to receive events from the channel by invoking the PullStructuredEvent or TryPullStructuredEvent operations supported by the target IStructuredProxyPullSupplier instance. If the target object of this operation is already connected to a pull consumer object, the AlreadyConnected exception will be raised.
The ITxnStructuredProxyPullSupplier Interface
The ITxnStructuredProxyPullSupplier interface supports connections to the channel by consumers who will pull events from the channel as Structured Events. It adds transactional behavior of these events to the functions provided in the IStructuredProxyPullSupplier interface. Events pulled from the channel within the context of a transaction are not deleted from a proxy suppliers queue until the consumer performing the pull operation(s) commits the transaction. If the transaction aborts, the channel treats the event(s) as if they had not been pulled from the proxy supplier involved in the transaction. In this case, the application should discard any portion of the event(s) it had received during the transaction, as other effects of the transaction (e.g., database updates) will also be undone.
The ISequenceProxyPullSupplier Interface
The ISequenceProxyPullSupplier interface supports connections to the channel by consumers who will pull events from the channel as sequences of Structured Events. Through inheritance of the IProxySupplier interface, the ISequenceProxyPullSupplier interface supports administration of various QoS properties, administration of a list of associated filter objects, and a readonly attribute containing the reference of the IConsumerAdmin object which created it. In addition, this inheritance implies that a ISequenceProxyPullSupplier instance supports an operation which will return the list of event types which the proxy supplier will potentially by supplying, and an operation which can return information about the instances ability to accept a per-event QoS request.
The ISequenceProxyPullSupplier interface also inherits from the ISequencePullSupplier interface defined in the IMSNotifyComm module. This interface supports the operations which enable a consumer of sequences of Structured Events to pull them from the ISequenceProxyPullSupplier, and also the operation which can be invoked to close down the connection from the consumer to the ISequenceProxyPullSupplier. In addition, since the ISequencePullSupplier interface inherits from the INotifySubscribe interface, a ISequenceProxyPullSupplier can be notified whenever the list of event types which its associated consumer is interested in receiving changes. This notification occurs via the callback mechanism described in section 2.3.
Lastly, the ISequenceProxyPullSupplier interface defines a method that can be invoked by a pull-style consumer of sequences of Structured Events in order to establish a connection between the consumer and a notification channel over which the consumer will proceed to receive events.
ConnectSequencePullConsumer
The ConnectSequencePullConsumer operation accepts as an input parameter the reference to an object supporting the ISequencePullConsumer interface defined within the IMSNotifyComm module. This reference is that of a consumer which plans to pull events from the channel to which the target object is associated in the form of sequences of Structured Events. This operation is thus invoked in order to establish a connection between a pull-style consumer of events in the form of sequences of Structured Events, and the notification channel. Once established, the consumer can proceed to receive events from the channel by invoking the PullStructuredEvents or TryPullStructuredEvents operations supported by the target ISequenceProxyPullSupplier instance. If the target object of this operation is already connected to a pull consumer object, the AlreadyConnected exception will be raised.
The ITxnSequenceProxyPullSupplier Interface
The ITxnSequenceProxyPullSupplier interface supports connections to the channel by consumers who will pull events from the channel as a sequence of Structured Events. It adds transactional behavior of these events to the functions provided in the ISequenceProxyPullSupplier interface. Events pulled from the channel within the context of a transaction are not deleted from a proxy suppliers queue until the consumer performing the pull operation(s) commits the transaction. If the transaction aborts, the channel treats the event(s) as if they had not been pulled from the proxy supplier involved in the transaction. In this case, the application should discard any portion of the event(s) it had received during the transaction, as other effects of the transaction (e.g., database updates) will also be undone.
The IProxyPullConsumer Interface
The IProxyPullConsumer interface supports connections to the channel by suppliers who will make events available for pulling to the channel as untyped Anys. Note that such suppliers are identical to OMG Event Service pull-style suppliers of untyped events. The IProxyPullConsumer interface defined here, however, supports event filtering and configuration of various QoS properties. Thus, this interface enables OMG Event Service style untyped event suppliers to take advantage of these new features offered by the Notification Service.
Through inheritance of the IProxyConsumer interface, the IProxyPullConsumer interface supports administration of various QoS properties, administration of a list of associated filter objects, and a readonly attribute containing the reference of the ISupplierAdmin object which created it. In addition, this inheritance implies that a IProxyPullConsumer instance supports an operation which will return the list of event types which consumers connected to the same channel are interested in receiving, and an operation which can return information about the instances ability to accept a per-event QoS request.
The IProxyPullConsumer interface inherits the INotifyPublish interface defined in the IMSNotifyComm module, enabling its associated supplier to inform it whenever the list of event types which the supplier plans to supply changes. The IProxyPullConsumer interface also inherits from the IPullConsumer interface defined within the IMSEventComm module of the OMG Event Service. This interface supports the operation required to disconnect the IProxyPullConsumer from its associated supplier. Finally, the IProxyPullConsumer interface defines the operation which can be invoked by a pull supplier to establish the connection over which the pull supplier will send events to the channel.
ConnectAnyPullSupplier
The ConnectAnyPullSupplier operation accepts as an input parameter the reference to an object supporting the IPullSupplier interface defined within the IMSEventComm module of the OMG Event Service. This reference is that of a supplier which plans to make events available for pulling to the channel with which the target object is associated in the form of untyped Anys. This operation is thus invoked in order to establish a connection between a pull-style supplier of events in the form of Anys, and the notification channel. Once established, the channel can proceed to receive events from the supplier by invoking the Pull or TryPull operations supported by the supplier (whether the channel will invoke Pull or TryPull, and the frequency with which it will perform such invocations, is a detail which is specific to the implementation of the channel). If the target object of this operation is already connected to a pull supplier object, the AlreadyConnected exception will be raised. An implementation of the IProxyPullConsumer interface may impose additional requirements on the interface supported by a pull supplier (e.g., it may be designed to invoke some operation other than Pull or TryPull in order to receive events). If the pull supplier being connected does not meet those requirements, this operation raises the TypeError exception.
The IStructuredProxyPullConsumer Interface
The IStructuredProxyPullConsumer interface supports connections to the channel by suppliers who will make events available for pulling to the channel as Structured Events. Through inheritance of the IProxyConsumer interface, the IStructuredProxyPullConsumer interface supports administration of various QoS properties, administration of a list of associated filter objects, and a readonly attribute containing the reference of the ISupplierAdmin object which created it. In addition, this inheritance implies that a IStructuredProxyPullConsumer instance supports an operation which will return the list of event types which consumers connected to the same channel are interested in receiving, and an operation which can return information about the instances ability to accept a per-event QoS request.
The IStructuredProxyPullConsumer interface also inherits from the IStructuredPullConsumer interface defined in the IMSNotifyComm module. This interface supports the operation which can be invoked to close down the connection from the supplier to the IStructuredProxyPullConsumer. In addition, since the IStructuredPullConsumer interface inherits from the INotifyPublish interface, a supplier can inform the IStructuredProxyPullConsumer to which it is connected whenever the list of event types it plans to supply to the channel changes.
Lastly, the IStructuredProxyPullConsumer interface defines a method that can be invoked by a pull-style supplier of Structured Events in order to establish a connection between the supplier and a notification channel over which the supplier will proceed to send events.
ConnectStructuredPullSupplier
The ConnectStructuredPullSupplier operation accepts as an input parameter the reference to an object supporting the IStructuredPullSupplier interface defined within the IMSNotifyComm module. This reference is that of a supplier which plans to make events available for pulling to the channel with which the target object is associated in the form of Structured Events. This operation is thus invoked in order to establish a connection between a pull-style supplier of events in the form of Structured Events, and the notification channel. Once established, the channel can proceed to receive events from the supplier by invoking the PullStructuredEvent or TryPullStructuredEvent operations supported by the supplier (whether the channel will invoke PullStructuredEvent or TryPullStructuredEvent, and the frequency with which it will perform such invocations, is a detail which is specific to the implementation of the channel). If the target object of this operation is already connected to a pull supplier object, the AlreadyConnected exception will be raised. An implementation of the IStructuredProxyPullConsumer interface may impose additional requirements on the interface supported by a pull supplier (e.g., it may be designed to invoke some operation other than PullStructuredEvent or TryPullStructuredEvent in order to receive events). If the pull supplier being connected does not meet those requirements, this operation raises the TypeError exception.
The ISequenceProxyPullConsumer Interface
The ISequenceProxyPullConsumer interface supports connections to the channel by suppliers who will make events available for pulling to the channel as sequences of Structured Events. Through inheritance of the IProxyConsumer interface, the ISequenceProxyPullConsumer interface supports administration of various QoS properties, administration of a list of associated filter objects, and a readonly attribute containing the reference of the ISupplierAdmin object which created it. In addition, this inheritance implies that a ISequenceProxyPullConsumer instance supports an operation which will return the list of event types which consumers connected to the same channel are interested in receiving, and an operation which can return information about the instances ability to accept a per-event QoS request. The ISequenceProxyPullConsumer interface also inherits from the ISequencePullConsumer interface defined in the IMSNotifyComm module. This interface supports the operation which can be invoked to close down the connection from the supplier to the ISequenceProxyPullConsumer. In addition, since the ISequencePullConsumer interface inherits from the INotifyPublish interface, a supplier can inform the ISequenceProxyPullConsumer to which it is connected whenever the list of event types it plans to supply to the channel changes. Lastly, the ISequenceProxyPullConsumer interface defines a method that can be invoked by a pull-style supplier of sequences of Structured Events in order to establish a connection between the supplier and a notification channel over which the supplier will proceed to send events.
ConnectSequencePullSupplier
The ConnectSequencePullSupplier operation accepts as an input parameter the reference to an object supporting the ISequencePullSupplier interface defined within the IMSNotifyComm module. This reference is that of a supplier which plans to make events available for pulling to the channel with which the target object is associated in the form of sequences of Structured Events. This operation is thus invoked in order to establish a connection between a pull-style supplier of events in the form of sequences of Structured Events, and the notification channel. Once established, the channel can proceed to receive events from the supplier by invoking the PullStructuredEvents or TryPullStructuredEvents operations supported by the supplier (whether the channel will invoke PullStructuredEvents or TryPullStructuredEvents, and the frequency with which it will perform such invocations, is a detail which is specific to the implementation of the channel). If the target object of this operation is already connected to a pull supplier object, the AlreadyConnected exception will be raised. An implementation of the ISequenceProxyPullConsumer interface may impose additional requirements on the interface supported by a pull supplier (e.g., it may be designed to invoke some operation other than PullStructuredEvents or TryPullStructuredEvents in order to receive events). If the pull supplier being connected does not meet those requirements, this operation raises the TypeError exception.
The IProxyPushSupplier Interface
The IProxyPushSupplier interface supports connections to the channel by consumers who will receive events from the channel as untyped Anys. Note that such consumers are identical to OMG Event Service push-style consumers of untyped events. The IProxyPushSupplier interface defined here, however, supports event filtering and configuration of various QoS properties. Thus, this interface enables OMG Event Service style untyped event consumers to take advantage of these new features offered by the Notification Service.
Through inheritance of the IProxySupplier interface, the IProxyPushSupplier interface supports administration of various QoS properties, administration of a list of associated filter objects, mapping filters for event priority and lifetime, and a readonly attribute containing the reference of the IConsumerAdmin object which created it. In addition, this inheritance implies that a IProxyPushSupplier instance supports an operation which will return the list of event types which the proxy supplier will potentially by supplying, and an operation which can return information about the instances ability to accept a per-event QoS request. The IProxyPushSupplier interface inherits the INotifySubscribe interface defined in the IMSNotifyComm module, enabling it to be notified whenever its associated consumer changes the list of event types it is interested in receiving. This notification occurs via the callback mechanism described in section 2.3.
The IProxyPushSupplier interface also inherits from the IPushSupplier interface defined within the IMSEventComm module of the OMG Event Service. This interface supports the operation required to disconnect the IProxyPushSupplier from its associated consumer.
Lastly, the IProxyPushSupplier interface defines the operation which can be invoked by a push consumer to establish the connection over which the push consumer will receive events from the channel. The IProxyPushSupplier interface also defines a pair of operations which can suspend and resume the connection between a IProxyPushSupplier instance and its associated IPushConsumer. During the time such a connection is suspended, the IProxyPushSupplier will accumulate events destined for the consumer but not transmit them until the connection is resumed.
ConnectAnyPushConsumer
The ConnectAnyPushConsumer operation accepts as an input parameter the reference to an object supporting the IPushConsumer interface defined within the IMSEventComm module of the OMG Event Service. This reference is that of a consumer which will receive events from the channel with which the target object is associated in the form of untyped Anys. This operation is thus invoked in order to establish a connection between a push-style consumer of events in the form of Anys, and the notification channel. Once established, the IProxyPushSupplier will proceed to send events destined for the consumer to it by invoking its push operation. If the target object of this operation is already connected to a push consumer object, the AlreadyConnected exception will be raised. An implementation of the IProxyPushSupplier interface may impose additional requirements on the interface supported by a push consumer (e.g., it may be designed to invoke some operation other than push in order to transmit events). If the push consumer being connected does not meet those requirements, this operation raises the TypeError exception.
SuspendConnection
The SuspendConnection operation causes the target object supporting the IProxyPushSupplier interface to stop sending events to the IPushConsumer instance connected to it. This operation takes no input parameters and returns no values. If the connection has been previously suspended using this operation and not resumed by invoking ResumeConnection (described below), the ConnectionAlreadyInactive exception is raised. Otherwise, the IProxyPushSupplier will not forward events to the IPushConsumer connected to it until ResumeConnection is subsequently invoked. During this time, the IProxyPushSupplier will continue to queue events destined for the IPushConsumer, although events that time out prior to resumption of the connection will be discarded. Upon resumption of the connection, all queued events will be forwarded to the IPushConsumer.
ResumeConnection
The ResumeConnection operation causes the target object supporting the IProxyPushSupplier interface to resume sending events to the IPushConsumer instance connected to it. This operation takes no input parameters and returns no values. If the connection has not been previously suspended using this operation by invoking SuspendConnection (described above), the ConnectionAlreadyActive exception is raised. Otherwise, the IProxyPushSupplier will resume forwarding events to the IPushConsumer connected to it, including those which have been queued during the time the connection was suspended, and have not yet timed out.
The IStructuredProxyPushSupplier Interface
The IStructuredProxyPushSupplier interface supports connections to the channel by consumers who will receive events from the channel as Structured Events. Through inheritance of the IProxySupplier interface, the IStructuredProxyPushSupplier interface supports administration of various QoS properties, administration of a list of associated filter objects, and a readonly attribute containing the reference of the IConsumerAdmin object which created it. In addition, this inheritance implies that a IStructuredProxyPushSupplier instance supports an operation which will return the list of event types which the proxy supplier will potentially by supplying, and an operation which can return information about the instances ability to accept a per-event QoS request.
The IStructuredProxyPushSupplier interface also inherits from the IStructuredPushSupplier interface defined in the IMSNotifyComm module. This interface supports the operation which can be invoked to close down the connection from the consumer to the IStructuredProxyPushSupplier. In addition, since the IStructuredPushSupplier interface inherits from the INotifySubscribe interface, a IStructuredProxyPushSupplier can be notified whenever the list of event types which its associated consumer is interested in receiving changes. This notification occurs via the callback mechanism described in section 2.3.
Lastly, the IStructuredProxyPushSupplier interface defines the operation which can be invoked by a push consumer to establish the connection over which the push consumer will receive events from the channel. The IStructuredProxyPushSupplier interface also defines a pair of operations which can suspend and resume the connection between a IStructuredProxyPushSupplier instance and its associated IStructuredPushConsumer. During the time such a connection is suspended, the IStructuredProxyPushSupplier will accumulate events destined for the consumer but not transmit them until the connection is resumed.
ConnectStructuredPushConsumer
The ConnectStructuredPushConsumer operation accepts as an input parameter the reference to an object supporting the IStructuredPushConsumer interface defined within the IMSNotifyComm module. This reference is that of a consumer which will receive events from the channel with which the target object is associated in the form of Structured Events. This operation is thus invoked in order to establish a connection between a push-style consumer of events in the form of Structured Events, and thenotification channel. Once established, the IStructuredProxyPushSupplier will proceed to send events destined for the consumer to it by invoking its PushStructuredEvent operation. If the target object of this operation is already connected to a push consumer object, the AlreadyConnected exception will be raised. An implementation of the IStructuredProxyPushSupplier interface may impose additional requirements on the interface supported by a push consumer (e.g., it may be designed to invoke some operation other than PushStructuredEvent in order to transmit events). If the push consumer being connected does not meet those requirements, this operation raises the TypeError exception.
SuspendConnection
The SuspendConnection operation causes the target object supporting the IStructuredProxyPushSupplier interface to stop sending events to the IStructuredPushConsumer instance connected to it. This operation takes no input parameters and returns no values. If the connection has been previously suspended using this operation and not resumed by invoking ResumeConnection (described below), the ConnectionAlreadyInactive exception is raised. Otherwise, the IStructuredProxyPushSupplier will not forward events to the IStructuredPushConsumer connected to it until ResumeConnection is subsequently invoked. During this time, the IStructuredProxyPushSupplier will continue to queue events destined for the IStructuredPushConsumer, although events that time out prior to resumption of the connection will be discarded. Upon resumption of the connection, all queued events will be forwarded to the IStructuredPushConsumer.
ResumeConnection
The ResumeConnection operation causes the target object supporting the IStructuredProxyPushSupplier interface to resume sending events to the IStructuredPushConsumer instance connected to it. This operation takes no input parameters and returns no values. If the connection has not been previously suspended using this operation by invoking SuspendConnection (described above), the ConnectionAlreadyActive exception is raised. Otherwise, the IStructuredProxyPushSupplier will resume forwarding events to the IStructuredPushConsumer connected to it, including those which have been queued during the time the connection was suspended, and have not yet timed out.
The ISequenceProxyPushSupplier Interface
The ISequenceProxyPushSupplier interface supports connections to the channel by consumers who will receive events from the channel as sequences of Structured Events. Through inheritance of the IProxySupplier interface, the ISequenceProxyPushSupplier interface supports administration of various QoS properties, administration of a list of associated filter objects, and a readonly attribute containing the reference of the IConsumerAdmin object which created it. In addition, this inheritance implies that a ISequenceProxyPushSupplier instance supports an operation which will return the list of event types which the proxy supplier will potentially by supplying, and an operation which can return information about the instances ability to accept a per-event QoS request.
The ISequenceProxyPushSupplier interface also inherits from the ISequencePushSupplier interface defined in the IMSNotifyComm module. This interface supports the operation which can be invoked to close down the connection from the consumer to the ISequenceProxyPushSupplier. In addition, since the ISequencePushSupplier interface inherits from the INotifySubscribe interface, a ISequenceProxyPushSupplier can be notified whenever the list of event types which its associated consumer is interested in receiving changes. This notification occurs via the callback mechanism described in section 2.3.
Lastly, the ISequenceProxyPushSupplier interface defines the operation which can be invoked by a push consumer to establish the connection over which the push consumer will receive events from the channel. The ISequenceProxyPushSupplier interface also defines a pair of operations which can suspend and resume the connection between a ISequenceProxyPushSupplier instance and its associated ISequencePushConsumer. During the time such a connection is suspended, the ISequenceProxyPushSupplier will accumulate events destined for the consumer but not transmit them until the connection is resumed.
ConnectSequencePushConsumer
The ConnectSequencePushConsumer operation accepts as an input parameter the reference to an object supporting the ISequencePushConsumer interface defined within the IMSNotifyComm module. This reference is that of a consumer which will receive events from the channel with which the target object is associated in the form of sequences of Structured Events. This operation is thus invoked in order to establish a connection between a push-style consumer of events in the form of sequences of Structured Events, and the notification channel. Once established, the ISequenceProxyPushSupplier will proceed to send events destined for the consumer to it by invoking its PushStructuredEvents operation. If the target object of this operation is already connected to a push consumer object, the AlreadyConnected exception will be raised. An implementation of the ISequenceProxyPushSupplier interface may impose additional requirements on the interface supported by a push consumer (e.g., it may be designed to invoke some operation other than PushStructuredEvents in order to transmit events). If the push consumer being connected does not meet those requirements, this operation raises the TypeError exception.
SuspendConnection
The SuspendConnection operation causes the target object supporting the ISequenceProxyPushSupplier interface to stop sending events to the ISequencePushConsumer instance connected to it. This operation takes no input parameters and returns no values. If the connection has been previously suspended using this operation and not resumed by invoking resume_connection (described below), the ConnectionAlreadyInactive exception is raised. Otherwise, the ISequenceProxyPushSupplier will not forward events to the ISequencePushConsumer connected to it until ResumeConnection is subsequently invoked. During this time, the ISequenceProxyPushSupplier will continue to queue events destined for the ISequencePushConsumer, although events that time out prior to resumption of the connection will be discarded. Upon resumption of the connection, all queued events will be forwarded to the ISequencePushConsumer.
ResumeConnection
The ResumeConnection operation causes the target object supporting the ISequenceProxyPushSupplier interface to resume sending events to the ISequencePushConsumer instance connected to it. This operation takes no input parameters and returns no values. If the connection has not been previously suspended using this operation by invoking SuspendConnection (described above), the ConnectionAlreadyActive exception is raised. Otherwise, the ISequenceProxyPushSupplier will resume forwarding events to the ISequencePushConsumer connected to it, including those which have been queued during the time the connection was suspended, and have not yet timed out.
The IConsumerAdmin Interface
The IConsumerAdmin interface defines the behavior supported by objects which create and manage lists of proxy supplier objects within a Notification Service event channel. Recall that a Notification Service event channel can have any number of IConsumerAdmin instances associated with it. Each such instance is responsible for creating and managing a list of proxy supplier objects that share a common set of QoS property settings, and a common set of filter objects. This feature enables clients to conveniently group proxy supplier objects within a channel into groupings that each support a set of consumers with a common set of QoS requirements and event subscriptions.
The IConsumerAdmin interface inherits the IQoSAdmin interface defined within the IMSNotification module, enabling each IConsumerAdmin instance to manage a set of QoS property settings. These QoS property settings are assigned as the default QoS property settings for any proxy supplier object created by a IConsumerAdmin instance. In addition, the IConsumerAdmin interface inherits from the IFilterAdmin interface defined within the IMSNotifyFilter module, enabling each IConsumerAdmin instance to maintain a list of filter objects. These filter objects encapsulate subscriptions that will apply to all proxy supplier objects that have been created by a given IConsumerAdmin instance. In order to enable optimizing the notification of a group of proxy supplier objects that have been created by the same IConsumerAdmin instance of changes to these shared filter objects, the IConsumerAdmin interface also inherits from the INotifySubscribe interface defined in the IMSNotifyComm module. This inheritance enables a IConsumerAdmin instance to be registered as the callback object for notification of subscription changes made upon filter objects. The IConsumerAdmin interface defined in the IMSNotifyChannelAdmin module also inherits from the IConsumerAdmin interface defined in the IMSEventChannelAdmin module. This inheritance enables clients to use the IConsumerAdmin interface defined in the IMSNotifyChannelAdmin module to create pure OMG Event Service style proxy supplier objects. Proxy supplier objects created in this manner may not support configuration of QoS properties, and may not have associated filter objects. In addition, proxy supplier objects created through the inherited IConsumerAdmin interface will not have unique identifiers associated with them, whereas proxy supplier objects created by invoking the operations supported by the IConsumerAdmin interface defined in the IMSNotifyChannelAdmin module will.
Locally, the IConsumerAdmin interface supports a readonly attribute which maintains a reference to the IEventChannel instance that created a given IConsumerAdmin instance. The IConsumerAdmin interface also supports a readonly attribute which contains a numeric identifier which will be assigned to an instance supporting this interface by its associated Notification Service event channel upon creation of the IConsumerAdmin instance. This identifier will be unique among all IConsumerAdmin instances created by a given channel.
As described above, due to inheritance from the IFilterAdmin interface, a IConsumerAdmin can maintain a list of filter objects that will be applied to all proxy suppliers it creates. Also recall that each proxy supplier may itself support a list of filter objects that apply only it. When combining multiple filter objects within each of these two lists of filter objects that may be associated with a given proxy supplier, OR semantics are applied. However when combining these two lists during the evaluation of a given event, either AND or OR semantics may be applied. The choice is determined by an input flag upon creation of the IConsumerAdmin, and the operator that will be used for this purpose by a given IConsumerAdmin is maintained in a readonly attribute.
The IConsumerAdmin interface also supports attributes which maintain references to priority and lifetime mapping filter objects. These mapping filter objects will be applied to all proxy supplier objects created by a given IConsumerAdmin instance. Each IConsumerAdmin instance assigns a unique numeric identifier to each proxy supplier object it maintains. The IConsumerAdmin interface supports attributes which maintain the list of these unique identifiers associated with the proxy pull and the proxy push suppliers created by a given IConsumerAdmin instance. The IConsumerAdmin interface also supports an operation which, given the unique identifier of a proxy supplier a given IConsumerAdmin instance has created as input, will return the object reference of that proxy supplier object. Finally, the IConsumerAdmin interface supports operations which can create the various styles of proxy supplier objects supported by the Notification Service event channel.
myID
The myID attribute is a readonly attribute which maintains the unique identifier of the target IConsumerAdmin instance which is assigned to it upon creation by the Notification Service event channel.
myChannel
The myChannel attribute is a readonly attribute which maintains the object reference of the Notification Service event channel that created a given IConsumerAdmin instance.
myOperator
The myOperator attribute is a readonly attribute which maintains the information regarding whether AND or OR semantics will be used during the evaluation of a given event against a set of filter objects, when combining the filter objects associated with the target IConsumerAdmin and those defined locally on a given proxy supplier.
priorityFilter
The priorityFilter attribute maintains a reference to a mapping filter object which affects the way in which each proxy supplier object created by the target IConsumerAdmin instance treats each event it receives with respect to priority. Note that each proxy supplier object also has an associated attribute which maintains a reference to a mapping filter object for the priority property. This local mapping filter object is only used by the proxy supplier in the event that the priorityFilter attribute of the IConsumerAdmin instance which created it is set to OBJECT_NIL. Otherwise, the mapping filter object referred to by the priorityFilter attribute of the IConsumerAdmin is used instead of the mapping filter object referred to by the priorityFilter attribute defined locally to the proxy supplier object.
lifetimeFilter
The lifetimeFilter attribute maintains a reference to a mapping filter object which affects the way in which each proxy supplier object created by the target IConsumerAdmin instance treats each event it receives with respect to lifetime. Note that each proxy supplier object also has an associated attribute which maintains a reference to a mapping filter object for the lifetime property. This local mapping filter object is only used by the proxy supplier in the event that the lifetimeFilter attribute of the IConsumerAdmin instance which created it is set to OBJECT_NIL. Otherwise, the mapping filter object referred to by the lifetimeFilter attribute of the IConsumerAdmin is used instead of the mapping filter object referred to by the lifetimeFilter attribute defined locally to the proxy supplier object.
pullSuppliers
The pullSuppliers attribute is a readonly attribute which contains the list of unique identifiers which have been assigned by a IConsumerAdmin instance to each pull-style proxy supplier object it has created.
pushSuppliers
The push_suppliers attribute is a readonly attribute which contains the list of unique identifiers which have been assigned by a IConsumerAdmin instance to each push-style proxy supplier object it has created.
GetProxySupplier
The GetProxySupplier operation accepts as an input parameter the numeric unique identifier associated with one of the proxy supplier objects which has been created by the target IConsumerAdmin instance. If the input parameter does correspond to the unique identifier of a proxy supplier object that has been created by the target IConsumerAdmin instance, that proxy supplier objects reference is returned as the result of the operation. Otherwise, the ProxyNotFound exception is raised.
ObtainNotificationPullSupplier
The ObtainNotificationPullSupplier operation can create instances of the various types of pull-style proxy supplier objects defined within the IMSNotifyChannelAdmin module. Recall that three varieties of pull-style proxy supplier objects are defined within this module: instances of the IProxyPullSupplier interface support connections to pull consumers which receive events as Anys, instances of the IStructuredProxyPullSupplier interface support connections to pull consumers which receive events as Structured Events, and instances of the ISequenceProxyPullSupplier interface support connections to pull consumers which receive events as sequences of Structured Events.
The ObtainNotificationPullSupplier operation thus accepts as an input parameter a flag which indicates which style of pull-style proxy supplier instance should be created. If the number of consumers currently connected to the channel with which the target IConsumerAdmin object is associated exceeds the value of the maxConsumers administrative property, the AdminLimitExceeded exception is raised. Otherwise, the target IConsumerAdmin creates the new pull-style proxy supplier instance and assigns a numeric identifier to it that is unique among all proxy suppliers it has created. The unique identifier is returned as the output parameter of the operation, and the reference to the new proxy supplier instance is returned as the operation result.
ObtainNotificationPushSupplier
The ObtainNotificationPushSupplier operation can create instances of the various types of push-style proxy supplier objects defined within the IMSNotifyChannelAdmin module. Recall that three varieties of push-style proxy supplier objects are defined within this module: instances of the IProxyPushSupplier interface support connections to push consumers which receive events as Anys, instances of the IStructuredProxyPushSupplier interface support connections to push consumers which receive events as Structured Events, and instances of the ISequenceProxyPushSupplier interface support connections to push consumers which receive events as sequences of Structured Events. The ObtainNotificationPushSupplier operation thus accepts as an input parameter a flag which indicates which style of push-style proxy supplier instance should be created. If the number of consumers currently connected to the channel with which the target IConsumerAdmin object is associated exceeds the value of the maxConsumers administrative property, the AdminLimitExceeded exception is raised. Otherwise, the target IConsumerAdmin creates the new push-style proxy supplier instance and assigns a numeric identifier to it that is unique among all proxy suppliers it has created. The unique identifier is returned as the output parameter of the operation, and the reference to the new proxy supplier instance is returned as the operation result.
ObtainTxnNotificationPullSupplier
The ObtainTxnNotificationPullSupplier operation can create instances of the transactional variants of the pull style proxy supplier interfaces defined within the IMSNotifyChannelAdmin module. Recall that three varieties of transactional pull-style proxy supplier objects are defined within this module: instances of the ITxnProxyPullSupplier interface supporting connections to pull consumers which receive events as Anys, instances of the ITxnStructuredProxyPullSupplier interface supporting connections to pull consumers which receive events as Structured Events, and instances of the ITxnSequenceProxyPullSupplier interface supporting connections to pull consumers which receive events as sequences of Structured Events. All these interfaces are intended for consumers who require transactional semantics while pulling events from the channel.
The ObtainTxnNotificationPullSupplier operation thus accepts as an input parameter a flag which indicates which style of transactional pull-style proxy supplier instance should be created. If the number of consumers currently connected to the channel with which the target IConsumerAdmin object is associated exceeds the value of the maxConsumers administrative property, the AdminLimitExceeded exception is raised. Otherwise, the target IConsumerAdmin creates the new transactional pull-style proxy supplier instance and assigns a numeric identifier to it that is unique among all proxy suppliers it has created. The unique identifier is returned as the output parameter of the operation, and the reference to the new transactional proxy supplier instance is returned as the operation result.
The ISupplierAdmin Interface
The ISupplierAdmin interface defines the behavior supported by objects which create and manage lists of proxy consumer objects within a Notification Service event channel. Recall that a Notification Service event channel can have any number of ISupplierAdmin instances associated with it. Each such instance is responsible for creating and managing a list of proxy consumer objects that share a common set of QoS property settings, and a common set of filter objects. This feature enables clients to conveniently group proxy consumer objects within a channel into groupings that each support a set of suppliers with a common set of QoS requirements, and that make common event forwarding decisions driven by the association of a common set of filter objects. The ISupplierAdmin interface inherits the IQoSAdmin interface defined within the IMSNotification module, enabling each ISupplierAdmin instance to manage a set of QoS property settings. These QoS property settings are assigned as the default QoS property settings for any proxy consumer object created by a ISupplierAdmin instance. In addition, the ISupplierAdmin interface inherits from the IFilterAdmin interface defined within the IMSNotifyFilter module, enabling each ISupplierAdmin instance to maintain a list of filter objects. These filter objects encapsulate subscriptions that will apply to all proxy consumer objects that have been created by a given ISupplierAdmin instance. In order to enable optimizing the notification of a group of proxy consumer objects that have been created by the same ISupplierAdmin instance of changes to the types of events being offered by suppliers, the ISupplierAdmin interface also inherits from the INotifyPublish interface defined in the IMSNotifyComm module. This inheritance enables a ISupplierAdmin instance to be the target of an offer_change request made by a supplier object, and for the change in event types being offered to be shared by all proxy consumer objects which were created by the target ISupplierAdmin.
The ISupplierAdmin interface defined in the IMSNotifyChannelAdmin module also inherits from the ISupplierAdmin interface defined in the IMSEventChannelAdmin module. This inheritance enables clients to use the ISupplierAdmin interface defined in the IMSNotifyChannelAdmin module to create pure OMG Event Service style proxy consumer objects. Proxy consumer objects created in this manner may not support configuration of QoS properties, and may not have associated filter objects. In addition, proxy consumer objects created through the inherited ISupplierAdmin interface will not have unique identifiers associated with them, whereas proxy consumer objects created by invoking the operations supported by the ISupplierAdmin interface defined in the IMSNotifyChannelAdmin module will. Locally, the ISupplierAdmin interface supports a readonly attribute which maintains a reference to the IEventChannel instance that created a given ISupplierAdmin instance. The ISupplierAdmin interface also supports a readonly attribute which contains a numeric identifier which will be assigned to an instance supporting this interface by its associated Notification Service event channel upon creation of the ISupplierAdmin instance. This identifier will be unique among all ISupplierAdmin instances created by a given channel.
As described above, due to inheritance from the IFilterAdmin interface, a ISupplierAdmin can maintain a list of filter objects that will be applied to all proxy consumers it creates. Also recall that each proxy consumer may itself support a list of filter objects that apply only it. When combining multiple filter objects within each of these two lists of filter objects that may be associated with a given proxy consumer, OR semantics are applied. However when combining these two lists during the evaluation of a given event, either AND or OR semantics may be applied. The choice is determined by an input flag upon creation of the ISupplierAdmin, and the operator that will be used for this purpose by a given ISupplierAdmin is maintained in a readonly attribute.
Each ISupplierAdmin instance assigns a unique numeric identifier to each proxy consumer object it maintains. The ISupplierAdmin interface supports attributes which maintain the list of these unique identifiers associated with the proxy pull and the proxy push consumers created by a given ISupplierAdmin instance. The ISupplierAdmin interface also supports an operation which, given the unique identifier of a proxy consumer a given ISupplierAdmin instance has created as input, will return the object reference of that proxy consumer object. Finally, the ISupplierAdmin interface supports operations which can create the various styles of proxy consumer objects supported by the Notification Service event channel.
myID
The myID attribute is a readonly attribute which maintains the unique identifier of the target ISupplierAdmin instance which is assigned to it upon creation by the Notification Service event channel.
myChannel
The myChannel attribute is a readonly attribute which maintains the object reference of the Notification Service event channel that created a given ISupplierAdmin instance.
myOperator
The myOperator attribute is a readonly attribute which maintains the information regarding whether AND or OR semantics will be used during the evaluation of a given event against a set of filter objects, when combining the filter objects associated with the target ISupplierAdmin and those defined locally on a given proxy consumer.
pullConsumers
The pullConsumers attribute is a readonly attribute which contains the list of unique identifiers which have been assigned by a ISupplierAdmin instance to each pull-style proxy consumer object it has created.
pushConsumers
The push_consumers attribute is a readonly attribute which contains the list of unique identifiers which have been assigned by a ISupplierAdmin instance to each push-style proxy consumer object it has created.
GetProxyConsumer
The GetProxyConsumer operation accepts as an input parameter the numeric unique identifier associated with one of the proxy consumer objects which has been created by the target ISupplierAdmin instance. If the input parameter does correspond to the unique identifier of a proxy consumer object that has been created by the target ISupplierAdmin instance, that proxy consumer objects reference is returned as the result of the operation. Otherwise, the IProxyNotFound exception is raised.
ObtainNotificationPullConsumer
The ObtainNotificationPullConsumer operation can create instances of the various types of pull-style proxy consumer objects defined within the IMSNotifyChannelAdmin module. Recall that three varieties of pull-style proxy consumer objects are defined within this module: instances of the IProxyPullConsumer interface support connections to pull suppliers which send events as Anys, instances of the IStructuredProxyPullConsumer interface support connections to pull suppliers which send events as Structured Events, and instances of the ISequenceProxyPullConsumer interface support connections to pull suppliers which send events as sequences of Structured Events.
The ObtainNotificationPullConsumer operation thus accepts as an input parameter a flag which indicates which style of pull-style proxy consumer instance should be created. If the number of suppliers currently connected to the channel with which the target ISupplierAdmin object is associated exceeds the value of the maxSuppliers administrative property, the AdminLimitExceeded exception is raised. Otherwise, the target ISupplierAdmin creates the new pull-style proxy consumer instance and assigns a numeric identifier to it that is unique among all proxy consumers it has created. The unique identifier is returned as the output parameter of the operation, and the reference to the new proxy consumer instance is returned as the operation result.
ObtainNotificationPushConsumer
The ObtainNotificationPushConsumer operation can create instances of the various types of push-style proxy consumer objects defined within the IMSNotifyChannelAdmin module. Recall that three varieties of push-style proxy consumer objects are defined within this module: instances of the IProxyPushConsumer interface support connections to push suppliers which send events as Anys, instances of the IStructuredProxyPushConsumer interface support connections to push suppliers which send events as Structured Events, and instances of the ISequenceProxyPushConsumer interface support connections to push suppliers which send events as sequences of Structured Events.
The ObtainNotificationPushConsumer operation thus accepts as an input parameter a flag which indicates which style of push-style proxy consumer instance should be created. If the number of suppliers currently connected to the channel with which the target ISupplierAdmin object is associated exceeds the value of the maxSuppliers administrative property, the AdminLimitExceeded exception is raised. Otherwise, the target ISupplierAdmin creates the new push-style proxy consumer instance and assigns a numeric identifier to it that is unique among all proxy consumers it has created. The unique identifier is returned as the output parameter of the operation, and the reference to the new proxy consumer instance is returned as the operation result.
ObtainTxnNotificationPushConsumer
The ObtainTxnNotificationPushConsumer operation can create instances of the various types of transactional push-style proxy consumer objects defined within the IMSNotifyChannelAdmin module. Recall that three varieties of transactional push- style proxy consumer objects are defined within this module: instances of the ITxnProxyPushConsumer interface supporting connections to push suppliers which send events as Anys, instances of the ITxnStructuredProxyPushConsumer interface supporting connections to push suppliers which send events as Structured Events, and instances of the ITxnSequenceProxyPushConsumer interface supporting connections to push suppliers which send events as sequences of Structured Events. All these interfaces are intended for suppliers who require transactional semantics while pushing events to the channel.
The ObtainTxnNotificationPushConsumer operation thus accepts as an input parameter a flag which indicates which style of transactional push-style proxy consumer instance should be created. If the number of suppliers currently connected to the channel with which the target ISupplierAdmin object is associated exceeds the value of the maxSuppliers administrative property, the AdminLimitExceeded exception is raised. Otherwise, the target ISupplierAdmin creates the new transactional push-style proxy consumer instance and assigns a numeric identifier to it that is unique among all proxy consumers it has created. The unique identifier is returned as the output parameter of the operation, and the reference to the new transactional proxy consumer instance is returned as the operation result.
The IEventChannel Interface
The IEventChannel interface encapsulates the behaviors supported by a Notification Service event channel. This interface inherits from the IEventChannel interface defined within the IMSEventChannelAdmin module of the OMG Event Service, making an instance of the Notification Service IEventChannel interface fully backward compatible with an OMG Event Service style untyped event channel. Inheritance of the IEventChannel interface defined within the IMSEventChannelAdmin module enables an instance of the IEventChannel interface defined within the IMSNotifyChannelAdmin module to create event service style IConsumerAdmin and ISupplierAdmin instances. These instances can subsequently be used to create pure event service style proxy interfaces, which support connections to pure event service style suppliers and consumers. Note that while Notification Service style proxies and admin objects have unique identifiers associated with them, enabling their references to be obtained by invoking operations on the Notification Service style admin and event channel interfaces, Event Service style proxies and admin objects do not have associated unique identifiers, and thus cannot be returned by invoking an operation on the Notification Service style admin or event channel interfaces. The IEventChannel interface defined within the IMSNotifyChannelAdmin module also inherits from the IQoSAdmin and the IAdminPropertiesAdmin interfaces defined within the IMSNotification module. Inheritance of these interfaces enables a Notification Service style event channel to manage lists of associated QoS and administrative properties, respectively.
Locally, the IEventChannel interface supports a readonly attribute which maintains a reference to the IEventChannelFactory instance that created it. In addition, each instance of the IEventChannel interface has an associated default IConsumerAdmin and an associated default ISupplierAdmin instance, both of which exist upon creation of the channel and which have the unique identifier of zero (note that admin object identifiers only need to be unique among a given type of admin, implying that the identifiers assigned to IConsumerAdmin objects can overlap those assigned to ISupplierAdmin objects). The IEventChannel interface supports readonly attributes which maintain references to these default admin objects.
The IEventChannel interface supports operations which create new IConsumerAdmin and ISupplierAdmin instances. In addition, the IEventChannel interface supports operations which can return references to the IConsumerAdmin and ISupplierAdmin instances associated with a given IEventChannel instance, given the unique identifier of an admin object as input. Finally, the IEventChannel interface supports operations which return the sequence of unique identifiers of all IConsumerAdmin and ISupplierAdmin instances associated with a given IEventChannel instance.
myFactory
The myFactory attribute is a readonly attribute which maintains the object reference of the event channel factory that created a given Notification Service IEventChannel instance.
defaultConsumerAdmin
The defaultConsumerAdmin attribute is a readonly attribute which maintains a reference to the default IConsumerAdmin instance associated with the target IEventChannel instance. Each IEventChannel instance has an associated default IConsumerAdmin instance, which exists upon creation of the channel and is assigned the unique identifier of zero. Subsequently, clients can create additional Event Service style IConsumerAdmin instances by invoking the inherited forConsumers operation, and additional Notification Service style IConsumerAdmin instances by invoking the NewForConsumers operation defined by the IEventChannel interface.
defaultSupplierAdmin
The defaultSupplierAdmin attribute is a readonly attribute which maintains a reference to the default ISupplierAdmin instance associated with the target IEventChannel instance. Each IEventChannel instance has an associated default ISupplierAdmin instance, which exists upon creation of the channel and is assigned the unique identifier of zero. Subsequently, clients can create additional Event Service style ISupplierAdmin instances by invoking the inherited forSuppliers operation, and additional Notification Service style ISupplierAdmin instances by invoking the NewForSuppliers operation defined by the IEventChannel interface.
NewForConsumers
The NewForConsumers operation is invoked to create a new Notification Service style IConsumerAdmin instance. The operation accepts as an input parameter a boolean flag which indicates whether AND or OR semantics will be used when combining the filter objects associated with the newly created IConsumerAdmin instance with those associated with a supplier proxy which was created by the IConsumerAdmin during the evaluation of each event against a set of filter objects. The new instance is assigned a unique identifier by the target IEventChannel instance that is unique among all IConsumerAdmin instances currently associated with the channel. Upon completion, the operation returns the reference to the new IConsumerAdmin instance as the result of the operation, and the unique identifier assigned to the new IConsumerAdmin instance as the output parameter.
NewForSuppliers
The NewForSuppliers operation is invoked to create a new Notification Service style ISupplierAdmin instance. The operation accepts as an input parameter a boolean flag which indicates whether AND or OR semantics will be used when combining the filter objects associated with the newly created ISupplierAdmin instance with those associated with a consumer proxy which was created by the ISupplierAdmin during the evaluation of each event against a set of filter objects. The new instance is assigned a unique identifier by the target IEventChannel instance that is unique among all ISupplierAdmin instances currently associated with the channel. Upon completion, the operation returns the reference to the new ISupplierAdmin instance as the result of the operation, and the unique identifier assigned to the new ISupplierAdmin instance as the output parameter.
GetConsumerAdmin
The GetConsumerAdmin operation returns a reference to one of the IConsumerAdmin instances associated with the target IEventChannel instance. The operation accepts as an input parameter a numeric value which is intended to be the unique identifier of one of the IConsumerAdmin instances associated with the target IEventChannel instance. If this turns out to be the case, the object reference of the associated IConsumerAdmin instance is returned as the operation result. Otherwise, the AdminNotFound exception is raised.
Note that while a Notification Service style event channel can support both Event Service and Notification Service style IConsumerAdmin instances, only Notification Service style IConsumerAdmin instances have associated unique identifiers.
GetSupplierAdmin
The GetSupplierAdmin operation returns a reference to one of the ISupplierAdmin instances associated with the target IEventChannel instance. The operation accepts as an input parameter a numeric value which is intended to be the unique identifier of one of the ISupplierAdmin instances associated with the target IEventChannel instance. If this turns out to be the case, the object reference of the associated ISupplierAdmin instance is returned as the operation result. Otherwise, the AdminNotFound exception is raised.
Note that while a Notification Service style event channel can support both Event Service and Notification Service style ISupplierAdmin instances, only Notification Service style ISupplierAdmin instances have associated unique identifiers.
GetAllConsumeradmins
The GetAllConsumerAdmins operation takes no input parameters and returns a sequence of the unique identifiers assigned to all Notification Service style IConsumerAdmin instances which have been created by the target IEventChannel instance.
GetAllSupplierAdmins
The GetAllSupplierAdmins operation takes no input parameters and returns a sequence of the unique identifiers assigned to all Notification Service style ISupplierAdmin instances which have been created by the target IEventChannel instance.
The IEventChannelFactory Interface
The EventChannelFactory interface defines operations for creating and managing new Notification Service style event channels. It supports a routine that creates new instances of Notification Service event channels and assigns unique numeric identifiers to them. In addition, the IEventChannelFactory interface supports a routine which can return the unique identifiers assigned to all event channels created by a given instance of IEventChannelFactory, and another routine which, given the unique identifier of an event channel created by a target IEventChannelFactory instance, returns the object reference of that event channel.
CreateChannel
The CreateChannel operation is invoked to create a new instance of the Notification Service style event channel. This operation accepts two input parameters. The first input parameter is a list of name-value pairs which specify the initial QoS property settings for the new channel. The second input parameter is a list of name-value pairs which specify the initial administrative property settings for the new channel. If no implementation of the IEventChannel interface exists that can support all of the requested QoS property settings, the UnsupportedQoS exception is raised. This exception contains as data a sequence of data structures, each of which identifies the name of a QoS property in the input list whose requested setting could not be satisfied, along with an error code and a range of settings for the property which could be satisfied. The meanings of the error codes which might be returned are described in Table 2-4.
Likewise, if no implementation of the IEventChannel interface exists that can support all of the requested administrative property settings, the UnsupportedAdmin exception is raised. This exception contains as data a sequence of data structures, each of which identifies the name of an administrative property in the input list whose requested setting could not be satisfied, along with an error code and a range of settings for the property which could be satisfied. The meanings of the error codes which might be returned are described in Table 2-4.
If neither of these exceptions is raised, the CreateChannel operation will return a reference to a new Notification Service style event channel. In addition, the operation assigns to this new event channel a numeric identifier which is unique among all event channels created by the target object. This numeric identifier is returned as an output parameter.
GetAll Channels
The GetAllChannels operation returns a sequence of all of the unique numeric identifiers corresponding to Notification Service event channels which have been created by the target object.
GetEventChannel
The GetEventChannel operation accepts as input a numeric value which is supposed to be the unique identifier of a Notification Service event channel that has been created by the target object. If this input value does not correspond to such a unique identifier, the ChannelNotFound exception is raised. Otherwise, the operation returns the object reference of the Notification Service event channel corresponding to the input identifier.
3.5 The IMSTypedNotifyChannelAdmin Module
The IMSTypedNotifyChannelAdmin module defines the interfaces necessary to create, configure, and administer instances of a Notification Service typed event channel. The Notification Service typed event channel is essentially a hybrid of the typed event channel defined by the OMG Event Service, and the Notification Service event channel described in the previous section. The Notification Service typed event channel supports typed event service clients, exactly as defined in the OMG Event Service, but provides the advantages of QoS administration of the channel, admin, and proxy interfaces, and also enables filtering to be performed on typed events. Through inheritance of analogous interfaces defined in the IMSTypedEventChannelAdmin module of the OMG Event Service, a Notification Service typed event channel supports backward compatibility with an Event Service typed event channel. In addition, the IMSTypedNotifyChannelAdmin module defines new versions of the ITypedEventChannel, admin, and proxy interfaces that support connections from clients who will communication via typed events, but also desire the ability to configure their connections to the channel to support various QoS properties, and the ability to define filters based on the type and contents of typed events. The concepts involved with filter of typed events are described in section 2.7. The interfaces and modules which comprise the IMSTypedNotifyChannelAdmin module are specified below.
The ITypedProxyPushConsumer Interface
The ITypedProxyPushConsumer interface supports connections to the channel by suppliers who will push OMG Event Service style typed events to the channel. Note that such suppliers are identical to OMG Event Service push-style suppliers of typed events. The ITypedProxyPushConsumer interface defined here, however, supports event filtering and configuration of various QoS properties. Thus, this interface enables OMG Event Service style typed event suppliers to take advantage of these new features offered by the Notification Service.
Through inheritance of the IProxyConsumer interface defined in the IMSNotifyChannelAdmin module, the ITypedProxyPushConsumer interface supports administration of various QoS properties, administration of a list of associated filter objects, and a readonly attribute containing the object reference of the ISupplierAdmin 1 instance which created a given ITypedProxyPushConsumer instance. In addition, this inheritance implies that a ITypedProxyPushConsumer instance supports an operation which will return the list of event types which consumers connected to the same channel are interested in receiving, and an operation which can return information about the instances ability to accept a per-event QoS request.
The ITypedProxyPushConsumer interface inherits the INotifyPublish interface defined in the IMSNotifyComm module, enabling its associated supplier to inform it whenever the list of event types which the supplier plans to supply changes. The ITypedProxyPushConsumer interface also inherits from the ITypedPushConsumer interface defined within the IMSTypedEventComm module of the OMG Event Service. This interface supports the event type specific operation(s) which the supplier connected to a ITypedProxyPushConsumer instance will invoke to send events to the channel in the form of typed events. And, since the ITypedPushConsumer interface inherits from the IPushConsumer interface defined in the IMSEventComm module, an instance supporting the ITypedProxyPushConsumer interface supports the standard push operation with which it can be supplied untyped events, and the operation required to disconnect the ITypedProxyPushConsumer from its associated supplier. Finally, the ITypedProxyPushConsumer interface defines the operation which can be invoked by a push supplier to establish the connection over which the push supplier will send events to the channel.
ConnectTypedPushSupplier
The ConnectTypedPushSupplier operation accepts as an input parameter the reference to an object supporting the IPushSupplier interface defined within the IMSEventComm module of the OMG Event Service. This reference is that of a supplier which plans to push typed events to the channel with which the target object is associated. This operation is thus invoked in order to establish a connection between a push-style supplier of typed events, and the notification channel. Once established, the supplier can proceed to send events to the channel by invoking the event type specific operation(s) supported by the target ITypedProxyPushConsumer instance. If the target object of this operation is already connected to a push supplier object, the AlreadyConnected exception will be raised.
Note that since there is no difference between the interfaces of suppliers of untyped and typed events, it would have sufficed to have the ITypedProxyPushConsumer interface to inherit from the IProxyPushConsumer interface defined in the IMSNotifyChannelAdmin module, and to not define a separate connect method for push-style suppliers of typed events. It was felt, however, that explicitly defining this operation makes the usage model of the ITypedProxyPushConsumer interface more intuitive.
The ITypedProxyPullSupplier Interface
The ITypedProxyPullSupplier interface supports connections to the channel by consumers who will pull OMG Event Service style typed events from the channel. Note that such consumers are identical to OMG Event Service pull-style consumers of typed events. The ITypedProxyPullSupplier interface defined here, however, supports event filtering and configuration of various QoS properties. Thus, this interface enables OMG Event Service style typed event consumers to take advantage of these new features offered by the Notification Service.
Through inheritance of the IProxySupplier interface, the ITypedProxyPullSupplier interface supports administration of various QoS properties, administration of a list of associated filter objects, mapping filters for event priority and lifetime, and a readonly attribute containing the object reference of the IConsumerAdmin 1 instance which created a given ITypedProxyPullSupplier instance. In addition, this inheritance implies that a ITypedProxyPullSupplier instance supports an operation which will return the list of event types which the proxy supplier will potentially by supplying, and an operation which can return information about the instances ability to accept a per-event QoS request.
The ITypedProxyPullSupplier interface inherits the INotifySubscribe interface defined in the IMSNotifyComm module, enabling it to be notified whenever its associated consumer changes the list of event types it is interested in receiving. This notification occurs via the callback mechanism described in section 2.3.
The ITypedProxyPullSupplier interface also inherits from the ITypedPullSupplier interface defined within the IMSTypedEventComm module of the OMG Event Service. This interface supports the event type specific operation(s) which the consumer connected to a ITypedProxyPullSupplier instance will invoke to receive events from the channel in the form of typed events. And, since the ITypedPullSupplier interface inherits from the IPullSupplier interface defined in theIMSEventComm module, an instance supporting the ITypedProxyPullSupplier interface supports the standard Pull and TryPull operations with which it can supply untyped events, and the operation required to disconnect the ITypedProxyPullSupplier from its associated consumer. Finally, the ITypedProxyPullSupplier interface defines the operation which can be invoked by a pull consumer to establish the connection over which the pull consumer will receive events from the channel.
ConnectTypedPullConsumer
The ConnectTypedPullConsumer operation accepts as an input parameter the reference to an object supporting the IPullConsumer interface defined within the IMSEventComm module of the OMG Event Service. This reference is that of a consumer which plans to pull typed events from the channel with which the target object is associated. This operation is thus invoked in order to establish a connection between a pull-style consumer of typed events, and the notification channel. Once established, the consumer can proceed to receive events from the channel by invoking the event type specific operation(s) supported by the target ITypedProxyPullSupplier instance. If the target object of this operation is already connected to a pull consumer object, the AlreadyConnected exception will be raised.
Note that since there is no difference between the interfaces of consumers of untyped and typed events, it would have sufficed to have the ITypedProxyPullSupplier interface to inherit from the IProxyPullSupplier interface defined in the IMSNotifyChannelAdmin module, and to not define a separate connect method for pull-style consumers of typed events. It was felt, however, that explicitly defining this operation makes the usage model of the ITypedProxyPullSupplier interface more intuitive.
The ITypedProxyPullConsumer Interface
The ITypedProxyPullConsumer interface supports connections to the channel by suppliers who will make OMG Event Service style typed events available for pulling to the channel. Note that such suppliers are identical to OMG Event Service pull-style suppliers of typed events. The ITypedProxyPullConsumer interface defined here, however, supports event filtering and configuration of various QoS properties. Thus, this interface enables OMG Event Service style typed event suppliers to take advantage of these new features offered by the Notification Service.
Through inheritance of the IProxyConsumer interface, the IProxyPullConsumer interface supports administration of various QoS properties, administration of a list of associated filter objects, and a readonly attribute containing the object reference of the ISupplierAdmin 1 instance which created a given ITypedProxyPullConsumer instance. In addition, this inheritance implies that a ITypedProxyPullConsumer instance supports an operation which will return the list of event types which consumers connected to the same channel are interested in receiving, and an operation which can return information about the instances ability to accept a per-event QoS request.
The ITypedProxyPullConsumer interface inherits the INotifyPublish interface defined in the IMSNotifyComm module, enabling its associated supplier to inform it whenever the list of event types which the supplier plans to supply changes.
The IProxyPullConsumer interface also inherits from the IPullConsumer interface defined within the IMSEventComm module of the OMG Event Service. This interface supports the operation required to disconnect the ITypedProxyPullConsumer from its associated supplier. Finally, the ITypedProxyPullConsumer interface defines the operation which can be invoked by a typed pull supplier to establish the connection over which the typed pull supplier will send events to the channel.
ConnectTypedPullSupplier
The ConnectTypedPullSupplier operation accepts as an input parameter the reference to an object supporting the ITypedPullSupplier interface defined within the IMSTypedEventComm module of the OMG Event Service. This reference is that of a supplier which plans to make OMG Event Service style typed events available for pulling to the channel with which the target object is associated. This operation is thus invoked in order to establish a connection between a pull-style supplier of typed events, and the notification channel. Once established, the channel can proceed to receive events from the supplier by invoking the event type specific operation(s) supported by the supplier. If the target object of this operation is already connected to a typed pull supplier object, the AlreadyConnected exception will be raised. An implementation of the ITypedProxyPullConsumer interface may impose additional requirements on the interface supported by a typed pull supplier (e.g., it may be designed to invoke some specific pull-style operation to receive events). If the typed pull supplier being connected does not meet those requirements, this operation raises the TypeError exception.
The ITypedProxyPushSupplier Interface
The ITypedProxyPushSupplier interface supports connections to the channel by consumers who will receive OMG Event Service style events from the channel. Note that such consumers are identical to OMG Event Service push-style consumers of typed events. The ITypedProxyPushSupplier interface defined here, however, supports event filtering and configuration of various QoS properties. Thus, this interface enables OMG Event Service style typed event consumers to take advantage of these new features offered by the Notification Service.
Through inheritance of the IProxySupplier interface, the ITypedProxyPushSupplier interface supports administration of various QoS properties, administration of a list of associated filter objects, mapping filters for event priority and lifetime, and a readonly attribute containing the object reference of the IConsumerAdmin 1 instance which created a given ITypedProxyPushSupplier instance. In addition, this inheritance implies that a ITypedProxyPushSupplier instance supports an operation which will return the list of event types which the proxy supplier will potentially by supplying, and an operation which can return information about the instances ability to accept a per-event QoS request.
The ITypedProxyPushSupplier interface inherits the INotifySubscribe interface defined in the IMSNotifyComm module, enabling it to be notified whenever its associated consumer changes the list of event types it is interested in receiving. This notification occurs via the callback mechanism described in section 2.3. The ITypedProxyPushSupplier interface also inherits from the IPushSupplier interface defined within the IMSEventComm module of the OMG Event Service. This interface supports the operation required to disconnect the ITypedProxyPushSupplier from its associated consumer.
Lastly, the ITypedProxyPushSupplier interface defines the operation which can be invoked by a typed push consumer to establish the connection over which the typed push consumer will receive events from the channel. The ITypedProxyPushSupplier interface also defines a pair of operations which can suspend and resume the connection between a ITypedProxyPushSupplier instance and its associated ITypedPushConsumer. During the time such a connection is suspended, the ITypedProxyPushSupplier will accumulate events destined for the consumer but not transmit them until the connection is resumed.
ConnectTypedPushConsumer
The ConnectTypedPushConsumer operation accepts as an input parameter the reference to an object supporting the ITypedPushConsumer interface defined within the IMSTypedEventComm module of the OMG Event Service. This reference is that of a consumer which will receive OMG Event Service style typed events from the channel with which the target object is associated. This operation is thus invoked in order to establish a connection between a push-style consumer of typed events, and the notification channel. Once established, the ITypedProxyPushSupplier will proceed to send events destined for the consumer to it by invoking its event type specific push-style operation(s). If the target object of this operation is already connected to a typed push consumer object, the AlreadyConnected exception will be raised. An implementation of the ITypedProxyPushSupplier interface may impose additional requirements on the interface supported by a typed push consumer (e.g., it may be designed to invoke some specific operation in order to transmit events). If the typed push consumer being connected does not meet those requirements, this operation raises the TypeError exception.
SuspendConnection
The SuspendConnection operation causes the target object supporting the ITypedProxyPushSupplier interface to stop sending events to the ITypedPushConsumer instance connected to it. This operation takes no input parameters and returns no values. If the connection has been previously suspended using this operation and not resumed by invoking resume_connection (described below), the ConnectionAlreadyInactive exception defined in the IMSNotifyChannelAdmin module is raised. Otherwise, the ITypedProxyPushSupplier will not forward events to the ITypedPushConsumer connected to it until ResumeConnection is subsequently invoked. During this time, the ITypedProxyPushSupplier will continue to queue events destined for the ITypedPushConsumer, although events that time out prior to resumption of the connection will be discarded. Upon resumption of the connection, all queued events will be forwarded to the ITypedPushConsumer.
ResumeConnection
The ResumeConnection operation causes the target object supporting the ITypedProxyPushSupplier interface to resume sending events to the ITypedPushConsumer instance connected to it. This operation takes no input parameters and returns no values. If the connection has not been previously suspended using this operation by invoking SuspendConnection (described above), the ConnectionAlreadyActive exception defined in the IMSNotifyChannelAdmin module is raised. Otherwise, the ITypedProxyPushSupplier will resume forwarding events to the ITypedPushConsumer connected to it, including those which have been queued during the time the connection was suspended, and have not yet timed out.
The ITypedConsumerAdmin Interface
The ITypedConsumerAdmin interface defines the behavior supported by objects which create and manage lists of proxy supplier objects within a Notification Service typed event channel. Similar to its untyped counterpart, a Notification Service typed event channel can have any number of ITypedConsumerAdmin instances associated with it. Each such instance is responsible for creating and managing a list of proxy supplier objects that share a common set of QoS property settings, and a common set of filter objects. This feature enables clients to conveniently group proxy supplier objects within a channel into groupings that each support a set of consumers with a common set of QoS requirements and event subscriptions.
Note that the ITypedConsumerAdmin interface inherits from IConsumerAdmin interface defined in the IMSNotifyChannelAdmin module, and the ITypedConsumerAdmin interface defined in the IMSTypedEventChannelAdmin module. These inheritance relationships have several implications for a Notification Service style ITypedConsumerAdmin instance.
First, inheritance of the IConsumerAdmin interface defined in the IMSNotifyChannelAdmin module implies that in addition to being capable of creating and managing Notification Service style typed proxy supplier objects, a ITypedConsumerAdmin instance can also create and manage instances supporting any of the proxy supplier interfaces defined in the IMSNotifyChannelAdmin module. In addition, since the IConsumerAdmin interface defined in the IMSNotifyChannelAdmin module inherits from the IConsumerAdmin interface defined in the IMSEventChannelAdmin module, a ITypedConsumerAdmin can also create and manage OMG Event service style untyped proxy supplier objects. Likewise, inheritance of the ITypedConsumerAdmin interface defined in the IMSTypedEventChannelAdmin module implies that an instance supporting the IMSTypedNotifyChannelAdmins version of ITypedConsumerAdmin can create and manage OMG Event Service style typed proxy supplier objects as well.
Thus, instances supporting the ITypedConsumerAdmin interface defined in the IMSTypedNotifyChannelAdmin module can potentially create and manage instances supporting any of the proxy supplier interfaces defined in the IMSEventChannelAdmin, IMSNotifyChannelAdmin, IMSTypedEventChannelAdmin, and the IMSTypedNotifyChannelAdmin (due to locally defined factory operations) modules. The implication of this is that a Notification Service style typed event channel can support OMG Event Service style untyped and typed consumers, along with all variations of consumers defined in the Notification Service as clients.
Note also that the inherited IMSNotifyChannelAdmin::IConsumerAdmin interface provides an instance supporting the IMSTypedNotifyChannelAdmin::ITypedConsumerAdmin interface with the behaviors necessary to associate unique identifiers with the proxy supplier objects it creates. While the ITypedConsumerAdmin interface defined here is capable of creating OMG Event Service style untyped and typed proxy supplier objects, only instances of the proxy supplier interfaces defined in the Notification Service can have associated unique identifiers.
Similarly, the inheritance of the IConsumerAdmin interface defined in the IMSNotifyChannelAdmin module provides an instance supporting the ITypedConsumerAdmin interface defined in the IMSTypedNotifyChannelAdmin module with the behaviors necessary to maintain associated QoS property settings and filter objects. The relationships between the QoS property settings and filter objects to the proxy supplier objects created by a ITypedConsumerAdmin instance are identical to those described in section 3.4.21. Note again that QoS property settings and filter objects can only be associated with Notification Service style proxy suppliers, both typed and untyped.
Inheritance of the IConsumerAdmin interface defined in IMSNotifyChannelAdmin also implies that ITypedConsumerAdmin also inherits from the INotifySubscribe interface defined in IMSNotifyComm. This inheritance enables optimizing the notification of a group of proxy supplier objects that have been created by the same ITypedConsumerAdmin instance of changes to shared filter objects, since this inheritance enables a ITypedConsumerAdmin instance to be registered as the callback object for notification of subscription changes made upon filter objects. Lastly, inheritance of the IConsumerAdmin interface defined in IMSNotifyChannelAdmin implies that an instance of the ITypedConsumerAdmin interface supports readonly attributes that maintain the unique identifier of the instance supplied to it by its creating channel, the object reference of the creating channel, and the flag which indicates whether AND or OR semantics will be used when combining the filter objects associated with a ITypedConsumerAdmin with those defined on specific proxy suppliers created by the ITypedConsumerAdmin.
Locally, the ITypedConsumerAdmin interface supports the operations which create new Notification Service style typed proxy supplier instances. Note lastly that due to inheritance of the IConsumerAdmin interface defined in the IMSNotifyChannelAdmin module, an instance supporting the ITypedConsumerAdmin interface supports a readonly attribute which maintains a unique identifier assigned to the instance by the channel which created it.
ObtainTypedNotificationPullSupplier
The ObtainTypedNotificationPullSupplier operation is used to create a new Notification Service style proxy supplier instance which will support a connection to the channel with which the target ITypedConsumerAdmin instance is associated by a pull-style consumer of typed events. The operation accepts as input a string which identifies the name of the strongly typed interface that the newly created ITypedProxyPullSupplier instance should support. The consumer which connects to the new ITypedProxyPullSupplier would use this strongly typed interface to invoke operations to receive typed events.
If the target ITypedConsumerAdmin instance cannot locate an occurrence of the ITypedProxyPullSupplier interface which also supports the requested strongly typed interface, the InterfaceNotSupported exception defined the IMSTypedEventChannelAdmin module is raised. If the number of consumers currently connected to the channel with which the target ITypedConsumerAdmin object is associated exceeds the value of the maxConsumers administrative property, the AdminLimitExceeded exception is raised. Otherwise, the target ITypedConsumerAdmin instance creates a new instance supporting the ITypedProxyPullSupplier interface defined in the IMSTypedNotifyChannelAdmin module. This interface can subsequently be used for a pull-style consumer of typed events to establish a connection to the Notification Service typed event channel. Upon creating the new ITypedProxyPullSupplier instance, the target ITypedConsumerAdmin instance associates with it a unique identifier which it returns as an output parameter. This unique identifier could subsequently be used as the input parameter to the GetProxySupplier operation inherited by the target ITypedConsumerAdmin instance in order to obtain the reference to the newly created ITypedProxyPullSupplier instance. This reference is returned as the result of the ObtainTypedNotificationPullSupplier operation.
ObtainTypedNotificationPushSupplier
The ObtainTypedNotificationPushSupplier operation is used to create a new Notification Service style proxy supplier instance which will support a connection to the channel with which the target ITypedConsumerAdmin instance is associated by a push-style consumer of typed events. The operation accepts as input a string which identifies the name of a strongly typed interface that the newly created ITypedProxyPushSupplier instance should use when invoking operations upon its associated ITypedPushConsumer instance to send it events.
If the target ITypedConsumerAdmin instance cannot locate an implementation of the ITypedProxyPullSupplier interface which will use the requested strongly typed interface to send events to a ITypedPushConsumer, the NoSuchImplementation exception defined the IMSTypedEventChannelAdmin module is raised. If the number of consumers currently connected to the channel with which the target ITypedConsumerAdmin object is associated exceeds the value of the maxConsumers administrative property, the AdminLimitExceeded exception is raised. Otherwise, the target ITypedConsumerAdmin instance creates a new instance supporting the ITypedProxyPushSupplier interface defined in the IMSTypedNotifyChannelAdmin module. This interface can subsequently be used for a push-style consumer of typed events to establish a connection to the Notification Service typed event channel. Upon creating the new ITypedProxyPushSupplier instance, the target ITypedConsumerAdmin instance associates with it a unique identifier which it returns as an output parameter. This unique identifier could subsequently be used as the input parameter to the GetProxySupplier operation inherited by the target ITypedConsumerAdmin instance in order to obtain the reference to the newly created ITypedProxyPushSupplier instance. This reference is returned as the result of the ObtainTypedNotificationPushSupplier operation.
The ITypedSupplierAdmin Interface
The ITypedSupplierAdmin interface defines the behavior supported by objects which create and manage lists of proxy consumer objects within a Notification Service typed event channel. Similar to its untyped counterpart, a Notification Service typed event channel can have any number of ITypedSupplierAdmin instances associated with it. Each such instance is responsible for creating and managing a list of proxy consumer objects that share a common set of QoS property settings, and a common set of filter objects. This feature enables clients to conveniently group proxy supplier objects within a channel into groupings that each support a set of consumers with a common set of QoS requirements and event subscriptions.
Note that the ITypedSupplierAdmin interface inherits from ISupplierAdmin interface defined in the IMSNotifyChannelAdmin module, and the ITypedSupplierAdmin interface defined in the IMSTypedEventChannelAdmin module. These inheritance relationships have several implications for a Notification Service style ITypedSupplierAdmin instance.
First, inheritance of the ISupplierAdmin interface defined in the IMSNotifyChannelAdmin module implies that in addition to being capable of creating and managing Notification Service style typed proxy consumer objects, a ITypedSupplierAdmin instance can also create and manage instances supporting any of the proxy consumer interfaces defined in the IMSNotifyChannelAdmin module. In addition, since the ISupplierAdmin interface defined in the IMSNotifyChannelAdmin module inherits from the ISupplierAdmin interface defined in the IMSEventChannelAdmin module, a ITypedSupplierAdmin can also create and manage OMG Event service style untyped proxy consumer objects. Likewise, inheritance of the ITypedSupplierAdmin interface defined in the IMSTypedEventChannelAdmin module implies that an instance supporting the IMSTypedNotifyChannelAdmins version of ITypedSupplierAdmin can create and manage OMG Event Service style typed proxy consumer objects as well. Thus, instances supporting the ITypedSupplierAdmin interface defined in the IMSTypedNotifyChannelAdmin module can potentially create and manage instances supporting any of the proxy consumer interfaces defined in the
IMSEventChannelAdmin, IMSNotifyChannelAdmin, IMSTypedEventChannelAdmin, and the IMSTypedNotifyChannelAdmin (due to locally defined factory operations) modules. The implication of this is that a Notification Service style typed event channel can support OMG Event Service style untyped and typed suppliers, along with all variations of suppliers defined in the Notification Service as clients.
Note also that the inherited IMSNotifyChannelAdmin::ISupplierAdmin interface provides an instance supporting the IMSTypedNotifyChannelAdmin::ITypedSupplierAdmin interface with the behaviors necessary to associate unique identifiers with the proxy consumer objects it creates. While the ITypedSupplierAdmin interface defined here is capable of creating OMG Event Service style untyped and typed proxy supplier objects, only instances of the proxy supplier interfaces defined in the Notification Service can have associated unique identifiers.
Similarly, the inheritance of the ISupplierAdmin interface defined in the IMSNotifyChannelAdmin module provides an instance supporting the ITypedSupplierAdmin interface defined in the IMSTypedNotifyChannelAdmin module with the behaviors necessary to maintain associated QoS property settings and filter objects. The relationships between the QoS property settings and filter objects to the proxy consumer objects created by a ITypedSupplierAdmin instance are identical to those described in section 3.4.22. Note again that QoS property settings and filter objects can only be associated with Notification Service style proxy consumers, both typed and untyped.
Inheritance of the ISupplierAdmin interface defined in IMSNotifyChannelAdmin also implies that ITypedSupplierAdmin also inherits from the INotifyPublish interface defined in IMSNotifyComm. This inheritance enables optimizing the notification of a group of proxy consumer objects that have been created by the same ITypedSupplierAdmin instance of changes to the types of events being offered to them by suppliers, since this inheritance enables a ITypedSupplierAdmin instance to be the target of an OfferChange operation. Lastly, inheritance of the ISupplierAdmin interface defined in IMSNotifyChannelAdmin implies that an instance of the ITypedSupplierAdmin interface supports readonly attributes that maintain the unique identifier of the instance supplied to it by its creating channel, the object reference of the creating channel, and the flag which indicates whether AND or OR semantics will be used when combining the filter objects associated with a ITypedSupplierAdmin with those defined on specific proxy consumers created by the ITypedSupplierAdmin. Locally, the ITypedSupplierAdmin interface supports the operations which create new Notification Service style typed proxy consumer instances. Note lastly that due to inheritance of the ISupplierAdmin interface defined in the IMSNotifyChannelAdmin module, an instance supporting the ITypedSupplierAdmin interface supports a readonly attribute which maintains a unique identifier assigned to the instance by the channel which created it.
oOtainTypedNotificationPushConsumer
The ObtainTypedNotificationPushConsumer operation is used to create a new Notification Service style proxy consumer instance which will support a connection to the channel with which the target ITypedSupplierAdmin instance is associated by a push-style supplier of typed events. The operation accepts as input a string which identifies the name of the strongly typed interface that the newly created ITypedProxyPushConsumer instance should support. The supplier which connects to the new ITypedProxyPushConsumer would use this strongly typed interface to invoke operations to send typed events to the channel. If the target ITypedSupplierAdmin instance cannot locate an occurrence of the ITypedProxyPushConsumer interface which also supports the requested strongly typed interface, the InterfaceNotSupported exception defined the IMSTypedEventChannelAdmin module is raised. If the number of suppliers currently connected to the channel with which the target ITypedSupplierAdmin object is associated exceeds the value of the maxSuppliers administrative property, the AdminLimitExceeded exception is raised. Otherwise, the target ITypedSupplierAdmin instance creates a new instance supporting the ITypedProxyPushConsumer interface defined in the IMSTypedNotifyChannelAdmin module. This interface can subsequently be used for a push-style supplier of typed events to establish a connection to the Notification Service typed event channel. Upon creating the new ITypedProxyPushConsumer instance, the target ITypedSupplierAdmin instance associates with it a unique identifier which it returns as an output parameter. This unique identifier could subsequently be used as the input parameter to the GetProxyConsumer operation inherited by the target ITypedSupplierAdmin instance in order to obtain the reference to the newly created ITypedProxyPushConsumer instance. This reference is returned as the result of the ObtainTypedNotificationPushConsumer operation.
ObtainTypedNotificationPullConsumer
The ObtainTypedNotificationPullConsumer operation is used to create a new Notification Service style proxy consumer instance which will support a connection to the channel with which the target ITypedSupplierAdmin instance is associated by a pull-style supplier of typed events. The operation accepts as input a string which identifies the name of a strongly typed interface that the newly created ITypedProxyPullConsumer instance should use when invoking operations upon its associated ITypedPullSupplier instance to receive events.
If the target ITypedSupplierAdmin instance cannot locate an implementation of the ITypedProxyPullConsumer interface which will use the requested strongly typed interface to receive events from a ITypedPullSupplier, the NoSuchImplementation exception defined the IMSTypedEventChannelAdmin module is raised.If the number of suppliers currently connected to the channel with which the target ITypedSupplierAdmin object is associated exceeds the value of the maxSuppliers administrative property, the AdminLimitExceeded exception is raised. Otherwise, the target ITypedSupplierAdmin instance creates a new instance supporting the ITypedProxyPullConsumer interface defined in the IMSTypedNotifyChannelAdmin module. This interface can subsequently be used for a pull-style supplier of typed events to establish a connection to the Notification Service typed event channel. Upon creating the new ITypedProxyPullConsumer instance, the target ITypedSupplierAdmin instance associates with it a unique identifier which it returns as an output parameter. This unique identifier could subsequently be used as the input parameter to the GetProxyConsumer operation inherited by the target ITypedSupplierAdmin instance in order to obtain the reference to the newly created ITypedProxyPullConsumer instance. This reference is returned as the result of the ObtainTypedNotificationPullConsumer operation.
The ITypedEventChannel Interface
The ITypedEventChannel interface defines the behaviors supported by the Notification Service version of a typed event channel. The previous statement that such a channel is a hybrid between the Notification Service event channel defined in the IMSNotifyChannelAdmin module, and the typed event channel defined in the OMG Event Service, is evidenced in the fact that the ITypedEventChannel interface defined here inherits from the IEventChannel interface of the IMSNotifyChannelAdmin module, and the ITypedEventChannel interface of the IMSTypedEventChannelAdmin module.
Inheritance of the ITypedEventChannel of the IMSTypedEventChannel module essentially implies backward compatibility between the Notification Service style typed event channel, and the OMG Event Service style typed event channel. It means that pure OMG Event Service style typed admin instances, which can create pure OMG Event Service style typed proxy instances, which can support pure OMG Event Service style typed event clients, can be associated with the Notification Service style typed event channel. As usual, none of the pure OMG style objects will support QoS property configuration, associated filter objects, or administration by unique identifiers.
Inheritance of the IEventChannel interface defined in the IMSNotifyChannelAdmin module has several implications. First, since the IEventChannel interface defined in the IMSNotifyChannelAdmin module inherits the IEventChannel interface defined in the IMSEventChannelAdmin module, an instance of the ITypedEventChannel can support OMG Event Service style untyped admin instances, proxy instances, and client instances as well. Again, none of these will support associated QoS property settings, filter objects, or unique identifiers.
Inheritance of the IQoSAdmin and IAdminPropertiesAdmin interfaces defined in the IMSNotification module by the IEventChannel interface defined in the IMSNotifyChannelAdmin module implies that instances of the ITypedEventChannel interface can have associated QoS property and administrative property settings. In addition, due to locally defined attributes and behaviors of the inherited IEventChannel interface of the IMSNotifyChannelAdmin module, instances of the ITypedEventChannel have associated default IConsumerAdmin and ISupplierAdmin instances, and can also create and manage both styles of admin instance defined in IMSNotifyChannelAdmin by unique identifier. Lastly, inheritance of the IEventChannel interface defined in the IMSNotifyChannelAdmin module implies that a ITypedEventChannel instance supports a readonly attribute which maintains a reference to the factory that created it.
Finally, the ITypedEventChannel interface defines locally the operations required to create new instances of the ITypedConsumerAdmin and the ITypedSupplierAdmin interfaces defined in the IMSTypedNotifyChannelAdmin module. These instances also have associated unique identifiers, which can be used in conjunction with the get* operations inherited from the IEventChannel interface of the IMSNotifyChannelAdmin module. These admin instances should be used by typed Notification Service clients to establish connections to the channel.
NewForTypedNotificationConsumers
The NewForTypedConsumers operation is invoked to create a new Notification Service style ITypedConsumerAdmin instance. The operation accepts as an input parameter a boolean flag which indicates whether AND or OR semantics will be used when combining the filter objects associated with the newly created ITypedConsumerAdmin instance with those associated with a supplier proxy which was created by the ITypedConsumerAdmin during the evaluation of each event against a set of filter objects. The new instance is assigned a unique identifier by the target ITypedEventChannel instance that is unique among all IConsumerAdmin and ITypedConsumerAdmin instances currently associated with the channel. Upon completion, the operation returns the reference to the new ITypedConsumerAdmin instance as the result of the operation, and the unique identifier assigned to the new ITypedConsumerAdmin instance as the output parameter.
NewForTypedNotificationSuppliers
The NewForTypedSuppliers operation is invoked to create a new Notification Service style ITypedSupplierAdmin instance. The operation accepts as an input parameter a boolean flag which indicates whether AND or OR semantics will be used when combining the filter objects associated with the newly created ITypedSupplierAdmin instance with those associated with a consumer proxy which was created by the ITypedSupplierAdmin during the evaluation of each event against a set of filter objects. The new instance is assigned a unique identifier by the target ITypedEventChannel instance that is unique among all ISupplierAdmin and ITypedSupplierAdmin instances currently associated with the channel. Upon completion, the operation returns the reference to the new ITypedSupplierAdmin instance as the result of the operation, and the unique identifier assigned to the new ITypedSupplierAdmin instance as the output parameter.
The ITypedEventChannelFactory Interface
The iTypedEventChannelFactory interface defines an operation for creating new Notification Service style typed event channels. This interface also inherits from the iEventChannelFactory interface defined in the IMSNotifyChannelAdmin module. This inheritance implies that an instance supporting the iTypedEventChannelFactory interface also supports an operation which can return the list of unique numeric identifiers assigned to all channels that have been created by the such an instance, and another which, given the unique identifier of a channel that has been created by the target instance, can return the object reference associated with that channel. Lastly, this inheritance implies that an instance supporting the iTypedEventChannelFactory can serve as the factory and manager of both untyped and typed Notification Service style event channels.
CreateTypedChannel
The CreateTypedChannel operation is invoked to create a new instance of the Notification Service style typed event channel. This operation accepts two input parameters. The first input parameter is a list of name-value pairs which specify the initial QoS property settings for the new channel. The second input parameter is a list of name-value pairs which specify the initial administrative property settings for the new channel.
If no implementation of the ITypedEventChannel interface exists that can support all of the requested QoS property settings, the UnsupportedQoS exception defined in the IMSNotifyChannelAdmin module is raised. This exception contains as data a sequence of data structures, each of which identifies the name of a QoS property in the input list whose requested setting could not be satisfied, along with an error code and a range of settings for the property which could be satisfied. The meanings of the error codes which might be returned are described in Table 2-4.
Likewise, if no implementation of the ITypedEventChannel interface exists that can support all of the requested administrative property settings, the UnsupportedAdmin exception defined in the IMSNotifyChannelAdmin module is raised. This exception contains as data a sequence of data structures, each of which identifies the name of an administrative property in the input list whose requested setting could not be satisfied, along with an error code and a range of settings for the property which could be satisfied. The meanings of the error codes which might be returned are described in Table 2-4.
If neither of these exceptions is raised, the CreateTypedChannel operation will return a reference to a new Notification Service style typed event channel. In addition, the operation assigns to this new typed event channel a numeric identifier which is unique among all event channels created by the target object. This numeric identifier is returned as an output parameter.
CORBA IDL
#ifndef _EVENTCOMM_IDL_
#define _EVENTCOMM_IDL_
module IMSEventComm
{
exception Disconnected{};
interface IPushConsumer
{
void Push( in any data )
raises( Disconnected );
void DisconnectPushConsumer();
}; // IPushConsumer
interface IPushSupplier
{
void DisconnectPushSupplier();
}; // IPushSupplier
interface IPullSupplier
{
any Pull()
raises( Disconnected );
any TryPull( out boolean hasEvent )
raises( Disconnected );
void DisconnectPullSupplier();
}; // IPullSupplier
interface IPullConsumer
{
void DisconnectPullConsumer();
}; // IPullConsumer
}; // IMSEventComm
#endif // _EVENTCOMM_IDL_
#ifndef _EVENTCHANNELADMIN_IDL_
#define _EVENTCHANNELADMIN_IDL_
#include "EventComm.idl"
module IMSEventChannelAdmin
{
exception AlreadyConnected{};
exception TypeError{};
interface IProxyPushConsumer : IMSEventComm::IPushConsumer
{
void ConnectPushSupplier( in IMSEventComm::IPushSupplier pushSupplier )
raises( AlreadyConnected );
}; // IProxyPushConsumer
interface IProxyPullSupplier : IMSEventComm::IPullSupplier
{
void ConnectPullConsumer( in IMSEventComm::IPullConsumer pullConsumer )
raises( AlreadyConnected );
}; // IProxyPullSupplier
interface IProxyPullConsumer : IMSEventComm::IPullConsumer
{
void ConnectPullSupplier( in IMSEventComm::IPullSupplier pullSupplier )
raises( AlreadyConnected,
TypeError );
}; // IProxyPullConsumer
interface IProxyPushSupplier : IMSEventComm::IPushSupplier
{
void ConnectPushConsumer( in IMSEventComm::IPushConsumer pushConsumer )
raises( AlreadyConnected,
TypeError );
}; // IProxyPushSupplier
interface IConsumerAdmin
{
IProxyPushSupplier ObtainPushSupplier();
IProxyPullSupplier ObtainPullSupplier();
}; // IConsumerAdmin
interface ISupplierAdmin
{
IProxyPushConsumer ObtainPushConsumer();
IProxyPullConsumer ObtainPullConsumer();
}; // ISupplierAdmin
interface IEventChannel
{
IConsumerAdmin ForConsumers();
ISupplierAdmin ForSuppliers();
void Destroy();
}; // IEventChannel
}; // IMSEventChannelAdmin
#endif // _EVENTCHANNELADMIN_IDL_
#ifndef _TYPEDEVENTCOMM_IDL_
#define _TYPEDEVENTCOMM_IDL_
#include "EventComm.idl"
module IMSTypedEventComm
{
interface ITypedPushConsumer : IMSEventComm::IPushConsumer
{
IObject GetTypedConsumer();
}; // ITypedPushConsumer
interface ITypedPullSupplier : IMSEventComm::IPullSupplier
{
IObject GetTypedSupplier();
}; // ITypedPullSupplier
}; // IMSTypedEventComm
#endif // _TYPEDEVENTCOMM_IDL_
#ifndef _TYPEDEVENTCHANNELADMIN_IDL_
#define _TYPEDEVENTCHANNELADMIN_IDL_
#include "TypedEventComm.idl"
#include "EventChannelAdmin.idl"
module IMSTypedEventChannelAdmin
{
exception InterfaceNotSupported{};
exception NoSuchImplementation{};
typedef string Key;
interface ITypedProxyPushConsumer : IMSEventChannelAdmin::IProxyPushConsumer,
IMSTypedEventComm::ITypedPushConsumer{};
interface ITypedProxyPullSupplier : IMSEventChannelAdmin::IProxyPullSupplier,
IMSTypedEventComm::ITypedPullSupplier{};
interface ITypedSupplierAdmin : IMSEventChannelAdmin::ISupplierAdmin
{
TypedProxyPushConsumer ObtainTypedPushConsumer( in Key supportedInterface )
raises( InterfaceNotSupported );
IProxyPullConsumer ObtainTypedPullConsumer( in Key usesInterface )
raises( NoSuchImplementation );
}; // ITypedSupplierAdmin
interface ITypedConsumerAdmin : IMSEventChannelAdmin::IConsumerAdmin
{
ITypedProxyPullSupplier ObtainTypedPullSupplier( in Key supportedInterface )
raises( InterfaceNotSupported );
IProxyPushSupplier ObtainTypedPushSupplier( in Key usesInterface )
raises( NoSuchImplementation );
}; // ITypedConsumerAdmin
interface ITypedEventChannel
{
ITypedConsumerAdmin ForConsumers();
ITypedSupplierAdmin ForSuppliers();
void Destroy();
}; // ITypedEventChannel
}; // IMSTypedEventChannelAdmin
#endif // _TYPEDEVENTCHANNELADMIN_IDL_
#ifndef _NOTIFICATION_IDL_
#define _NOTIFICATION_IDL_
#include "Trading.idl"
module IMSNotification
{
typedef IMSTrading::PropertySeq OptionalHeaderFields;
typedef IMSTrading::PropertySeq FilterableEventBody;
typedef IMSTrading::PropertySeq QoSProperties;
typedef IMSTrading::PropertySeq AdminProperties;
struct EventType
{
string domain_name;
string type_name;
};
typedef sequence EventTypeSeq;
struct PropertyRange
{
IMSTrading::PropertyName name;
IMSTrading::PropertyValue low_val;
IMSTrading::PropertyValue high_val;
};
typedef sequence PropertyRangeSeq;
enum QoSError_code
{
UNSUPPORTED_PROPERTY,
UNAVAILABLE_PROPERTY,
UNSUPPORTED_VALUE,
UNAVAILABLE_VALUE,
BAD_PROPERTY,
BAD_TYPE,
BAD_VALUE
};
struct PropertyError
{
QoSError_code code;
PropertyRange available_range;
};
typedef sequence PropertyErrorSeq;
exception UnsupportedQoS { PropertyErrorSeq qos_err; };
exception UnsupportedAdmin { PropertyErrorSeq admin_err; };
// Define the Structured Event structure
struct FixedEventHeader
{
EventType event_type;
string event_name;
};
struct EventHeader
{
FixedEventHeader fixed_header;
OptionalHeaderFields variable_header;
};
struct StructuredEvent
{
EventHeader header;
FilterableEventBody filterable_data;
any remainder_of_body;
};
typedef sequence EventBatch;
// The following constant declarations define the standard
// QoS property names and the associated values each property
// can take on. The name/value pairs for each standard property
// are grouped, beginning with a string constant defined for the
// property name, followed by the values the property can take on.
const string EventReliability = "EventReliability";
const short BestEffort = 0;
const short Persistent = 1;
const string ConnectionReliability = "ConnectionReliability";
// Can take on the same values as EventReliability
const string Priority = "Priority";
const short LowestPriority = -32767;
const short HighestPriority = 32767;
const short DefaultPriority = 0;
const string StartTime = "StartTime";
// StartTime takes a value of type TimeBase::UtcT when placed
// in an event header. StartTime can also be set to either
// TRUE or FALSE at the Proxy level, indicating whether or not the
// Proxy supports the setting of per-message start times.
const string StopTime = "StopTime";
// StopTime takes a value of type TimeBase::UtcT when placed
// in an event header. StopTime can also be set to either
// TRUE or FALSE at the Proxy level, indicating whether or not the
// Proxy supports the setting of per-message stop times.
const string Timeout = "Timeout";
// Timeout take on a value of type TimeBase::TimeT
const string OrderPolicy = "OrderPolicy";
const short AnyOrder = 0;
const short FifoOrder = 1;
const short PriorityOrder = 2;
const short DeadlineOrder = 3;
const string DiscardPolicy = "DiscardPolicy";
// DiscardPolicy takes on the same values as OrderPolicy plus
const short LifoOrder = 4;
const string MaximumBatchSize = "MaximumBatchSize";
// MaximumBatchSize takes on a value of type long
const string PacingInterval = "PacingInterval";
// PacingInterval takes on a value of type TimeBase::TimeT
interface IQoSAdmin
{
QoSProperties GetQos();
void SetQos( in IQoSProperties qos )
raises( UnsupportedQoS );
void ValidateQos( in IQoSProperties requiredQos,
out PropertyRangeSeq available_qos )
raises( UnsupportedQoS );
}; // QoSAdmin
// Admin properties are defined in similar manner as QoS
// properties. The only difference is that these properties
// are related to channel administration policies, as opposed
// to message quality of service
const string MaxQueueLength = "MaxQueueLength";
// MaxQueuelength takes on a value of type long
const string MaxConsumers = "MaxConsumers";
// MaxConsumers takes on a value of type long
const string MaxSuppliers = "MaxSuppliers";
// MaxSuppliers take on a value of type long
interface IAdminPropertiesAdmin
{
IAdminProperties GetAdmin();
void SetAdmin( in IAdminProperties admin )
raises( UnsupportedAdmin );
}; // IAdminPropertiesAdmin
}; //IMSNotification
#endif // _NOTIFICATION_IDL_
#ifndef _NOTIFYCOMM_IDL_
#define _NOTIFYCOMM_IDL_
module IMSNotifyComm
{
exception InvalidEventType { IMSNotification::EventType type; };
interface INotifyPublish
{
void OfferChange( in IMSNotification::EventTypeSeq added,
in IMSNotification::EventTypeSeq removed )
raises( InvalidEventType );
}; // INotifyPublish
interface INotifySubscribe
{
void SubscriptionChange( in IMSNotification::EventTypeSeq added,
in IMSNotification::EventTypeSeq removed )
raises( InvalidEventType );
}; // INotifySubscribe
interface ITxnPushConsumer : INotifyPublish,
IMSEventComm::IPushConsumer,
IMSTransactions::ITransactionalObject
{
}; // ITxnPushConsumer
interface ITxnPullSupplier : INotifySubscribe,
IMSEventComm::IPullSupplier,
IMSTransactions::ITransactionalObject
{
}; // ITxnPullSupplier
interface IStructuredPushConsumer : INotifyPublish
{
void PushStructuredEvent( in IMSNotification::StructuredEvent notification )
raises( IMSEventComm::Disconnected );
void DisconnectStructuredPushConsumer();
}; // IStructuredPushConsumer
interface ITxnStructuredPushConsumer : IStructuredPushConsumer,
IMSTransactions::ITransactionalObject
{
}; // ITxnStructuredPushConsumer
interface IStructuredPullConsumer : INotifyPublish
{
void DisconnectStructuredPullConsumer();
}; // IStructuredPullConsumer
interface IStructuredPullSupplier : INotifySubscribe
{
IMSNotification::StructuredEvent PullStructuredEvent()
raises( IMSEventComm::Disconnected );
IMSNotification::StructuredEvent TryPullStructuredEvent( out boolean hasEvent )
raises( IMSEventComm::Disconnected );
void DisconnectStructuredPullSupplier();
}; // IStructuredPullSupplier
interface ITxnStructuredPullSupplier : IStructuredPullSupplier,
IMSTransactions::ITransactionalObject
{
}; // ITxnStructuredPullSupplier
interface IStructuredPushSupplier : INotifySubscribe
{
void DisconnectStructuredPushSupplier();
}; // IStructuredPushSupplier
interface ISequencePushConsumer : INotifyPublish
{
void PushStructuredEvents( in IMSNotification:EventBatch notifications )
raises( IMSEventComm::Disconnected );
void DisconnectSequencePushConsumer();
}; // ISequencePushConsumer
interface ITxnSequencePushConsumer : ISequencePushConsumer,
IMSTransactions::ITransactionalObject
{
}; // ITxnSequencePushConsumer
interface ISequencePullConsumer : INotifyPublish
{
void DisconnectSequencePullConsumer();
}; // ISequencePullConsumer
interface ISequencePullSupplier : INotifySubscribe
{
IMSNotification::EventBatch PullStructuredEvents( in long maxNumber )
raises( IMSEventComm::Disconnected );
IMSNotification::StructuredEvent TryPullStructuredEvents(in long maxNumber,
out boolean haEvent )
raises( IMSEventComm::Disconnected );
void DisconnectSequencePullSupplier();
}; // ISequencePullSupplier
interface ITxnSequencePullSupplier : ISequencePullSupplier,
IMSTransactions::ITransactionalObject
{
}; // ITxnSequencePullSupplier
interface ISequencePushSupplier : INotifySubscribe
{
void DisconnectSequencePushSupplier();
}; // ISequencePushSupplier
}; // IMSNotifyComm
#endif // _NOTIFYCOMM_IDL_
#ifndef _NOTIFYCHANNELADMIN_IDL_
#define _NOTIFYCHANNELADMIN_IDL_
module IMSNotifyChannelAdmin
{
exception ConnectionAlreadyActive{};
exception ConnectionAlreadyInactive{};
// Forward declarations
interface ConsumerAdmin;
interface SupplierAdmin;
interface EventChannel;
interface EventChannelFactory;
interface IProxyConsumer : IMSNotification::IQoSAdmin,
IMSNotifyFilter::IFilterAdmin
{
readonly attribute ISupplierAdmin myAdmin;
IMSNotification::EventTypeSeq ObtainSubscriptionTypes();
void ValidateEventQos(in IMSNotification::QoSProperties requiredQos,
out IMSNotification::PropertyRangeSeq availableQos )
raises( IMSNotification::UnsupportedQoS );
}; // IProxyConsumer
interface IProxySupplier : IMSNotification::IQoSAdmin,
IMSNotifyFilter::IFilterAdmin
{
readonly attribute IConsumerAdmin myAdmin;
attribute IMSNotifyFilter::MappingFilter priorityFilter;
attribute IMSNotifyFilter::MappingFilter lifetimeFilter;
IMSNotification::EventypeSeq ObtainOfferedTypes();
void ValidateEventQos(in IMSNotification::QoSProperties requiredQos,
out IMSNotification::PropertyRangeSeq availableQos )
raises( IMSNotification::UnsupportedQoS );
}; // IProxySupplier
interface IProxyPushConsumer : IProxyConsumer,
IMSNotifyComm::INotifyPublish,
IMSEventComm::IPushConsumer
{
void ConnectAnyPushSupplier( in IMSEventComm::IPushSupplier pushSupplier )
raises( IMSEventChannelAdmin::AlreadyConnected );
}; // IProxyPushConsumer
interface ITxnProxyPushConsumer : IProxyPushConsumer,
IMSTransactions::ITransactionalObject
{
}; // ITxnProxyPushConsumer
interface IStructuredProxyPushConsumer : IProxyConsumer,
IMSNotifyComm::IStructuredPushConsumer
{
void ConnectStructuredPushSupplier( in IMSNotifyComm::IStructuredPushSupplier pushSupplier )
raises( IMSEventChannelAdmin::AlreadyConnected );
}; // IStructuredProxyPushConsumer
interface ITxnStructuredProxyPushConsumer : IStructuredProxyPushConsumer,
IMSTransactions::ITransactionalObject
{
}; // ITxnStructuredProxyPushConsumer
interface ISequenceProxyPushConsumer : IProxyConsumer,
IMSNotifyComm::ISequencePushConsumer
{
void ConnectSequencePushSupplier( in IMSNotifyComm::ISequencePushSupplier pushSupplier )
raises( IMSEventChannelAdmin::AlreadyConnected );
}; // ISequenceProxyPushConsumer
interface ITxnSequenceProxyPushConsumer : ISequenceProxyPushConsumer,
IMSTransactions::ITransactionalObject
{
}; // ITxnSequenceProxyPushConsumer
interface IProxyPullSupplier : IProxySupplier,
IMSNotifyComm::INotifySubscribe,
IMSEventComm::IPullSupplier
{
void ConnectAnyPullConsumer( in IMSEventComm::IPullConsumer pullConsumer )
raises( IMSEventChannelAdmin::AlreadyConnected );
}; // IProxyPullSupplier
interface ITxnProxyPullSupplier : IProxyPullSupplier,
IMSTransactions::ITransactionalObject
{
}; // ITxnProxyPullSupplier
interface IStructuredProxyPullSupplier : IProxySupplier,
IMSNotifyComm::IStructuredPullSupplier
{
void ConnectStructuredPullConsumer ( in IMSNotifyComm::IStructuredPullConsumer pullConsumer )
raises( IMSEventChannelAdmin::AlreadyConnected );
}; // IStructuredProxyPullSupplier
interface ITxnStructuredProxyPullSupplier : IStructuredProxyPullSupplier,
IMSTransactions::ITransactionalObject
{
}; // ITxnStructuredProxyPullSupplier
interface ISequenceProxyPullSupplier : IProxySupplier,
IMSNotifyComm::ISequencePullSupplier
{
void ConnectSequencePullConsumer( in IMSNotifyComm::ISequencePullConsumer pullConsumer )
raises( IMSEventChannelAdmin::AlreadyConnected );
}; // ISequenceProxyPullSupplier
interface ITxnSequenceProxyPullSupplier : ISequenceProxyPullSupplier,
IMSTransactions::ITransactionalObject
{
}; // ITxnSequenceProxyPullSupplier
interface IProxyPullConsumer : IProxyConsumer,
IMSNotifyComm::INotifyPublish,
IMSEventComm::IPullConsumer
{
void ConnectAnyPullSupplier( in IMSEventComm::IPullSupplier pullSupplier )
raises( IMSEventChannelAdmin::AlreadyConnected,
IMSEventChannelAdmin::TypeError );
}; // IProxyPullConsumer
interface IStructuredProxyPullConsumer : IProxyConsumer,
IMSNotifyComm::IStructuredPullConsumer
{
void ConnectStructuredPullSupplier( in IMSNotifyComm::IStructuredPullSupplier pullSupplier )
raises( IMSEventChannelAdmin::AlreadyConnected,
IMSEventChannelAdmin::TypeError );
}; // IStructuredProxyPullConsumer
interface ISequenceProxyPullConsumer : IProxyConsumer,
IMSNotifyComm::ISequencePullConsumer
{
void ConnectSequencePullSupplier ( in IMSNotifyComm::ISequencePullSupplier pullSupplier )
raises( IMSEventChannelAdmin::AlreadyConnected,
IMSEventChannelAdmin::TypeError );
}; // ISequenceProxyPullConsumer
interface IProxyPushSupplier : IProxySupplier,
IMSNotifyComm::INotifySubscribe,
IMSEventComm::IPushSupplier
{
void ConnectAnyPushConsumer( in IMSEventComm::IPushConsumer pushConsumer )
raises( IMSEventChannelAdmin::AlreadyConnected,
IMSEventChannelAdmin::TypeError );
void SuspendConnection()
raises( ConnectionAlreadyInactive );
void ResumeConnection()
raises( ConnectionAlreadyActive );
}; // IProxyPushSupplier
interface IStructuredProxyPushSupplier : IProxySupplier,
IMSNotifyComm::IStructuredPushSupplier
{
void ConnectStructuredPushConsumer ( in IMSNotifyComm::IStructuredPushConsumer pushConsumer )
raises( IMSEventChannelAdmin::AlreadyConnected,
IMSEventChannelAdmin::TypeError );
void suspendConnection()
raises( ConnectionAlreadyInactive );
void resumeConnection()
raises( ConnectionAlreadyActive );
}; // IStructuredProxyPushSupplier
interface ISequenceProxyPushSupplier : IProxySupplier,
IMSNotifyComm::ISequencePushSupplier
{
void ConnectSequencePushConsumer( in IMSNotifyComm::ISequencePushConsumer pushConsumer )
raises( IMSEventChannelAdmin::AlreadyConnected,
IMSEventChannelAdmin::TypeError );
void suspendConnection()
raises( ConnectionAlreadyInactive );
void resumeConnection()
raises( ConnectionAlreadyActive );
}; // ISequenceProxyPushSupplier
typedef long ProxyID;
typedef sequence ProxyIDSeq;
enum ClientType
{
ANY_EVENT,
STRUCTURED_EVENT,
SEQUENCE_EVENT
}; // ClientType
enum InterFilterGroupOperator { AND_OP, OR_OP };
typedef long AdminID;
typedef sequence AdminIDSeq;
exception AdminNotFound{};
exception ProxyNotFound{};
struct AdminLimit
{
IMSTrading::PropertyName name;
IMSTrading::PropertyValue value;
};
exception AdminLimitExceeded { AdminLimit admin_property_err; };
interface IConsumerAdmin : IMSNotification::IQoSAdmin,
IMSNotifyComm:INotifySubscribe,
IMSNotifyFilter::IFilterAdmin,
IMSEventChannelAdmin::IConsumerAdmin
{
readonly attribute AdminID myID;
readonly attribute EventChannel myChannel;
readonly attribute InterFilterGroupOperator myOperator;
attribute IMSNotifyFilter::MappingFilter priorityFilter;
attribute IMSNotifyFilter::MappingFilter lifetimeFilter;
readonly attribute ProxyIDSeq pullSuppliers;
readonly attribute ProxyIDSeq pushSuppliers;
ProxySupplier GetProxySupplier( in ProxyID proxyId )
raises( ProxyNotFound );
ProxySupplier ObtainNotificationPullSupplier( in ClientType ctype,
out ProxyID proxyId )
raises( AdminLimitExceeded );
ProxySupplier ObtainNotificationPushSupplier( in ClientType ctype,
out ProxyID proxyId )
raises( AdminLimitExceeded );
ProxySupplier ObtainTxnNotificationPullSupplier(in ClientType ctype,
out ProxyID proxyId )
raises( AdminLimitExceeded );
}; // IConsumerAdmin
interface ISupplierAdmin : IMSNotification::IQoSAdmin,
IMSNotifyComm::INotifyPublish,
IMSNotifyFilter::IFilterAdmin,
IMSEventChannelAdmin::ISupplierAdmin
{
readonly attribute AdminID myID;
readonly attribute EventChannel myChannel;
readonly attribute InterFilterGroupOperator myOperator;
readonly attribute ProxyIDSeq pullConsumers;
readonly attribute ProxyIDSeq pushConsumers;
ProxyConsumer GetProxyConsumer( in ProxyID proxyId )
raises( ProxyNotFound );
ProxyConsumer ObtainNotificationPullConsumer(in ClientType ctype,
out ProxyID proxyId )
raises( AdminLimitExceeded );
ProxyConsumer ObtainNotificationPushConsumer(in ClientType ctype,
out ProxyID proxyId )
raises( AdminLimitExceeded );
ProxyConsumer ObtainTxnNotificationPushConsumer(in ClientType ctype,
out ProxyID proxyId )
raises( AdminLimitExceeded );
}; // ISupplierAdmin
interface IEventChannel : IMSNotification::IQoSAdmin,
IMSNotification::IAdminPropertiesAdmin,
IMSEventChannelAdmin::IEventChannel
{
readonly attribute EventChannelFactory myFactory;
readonly attribute ConsumerAdmin defaultConsumerAdmin;
readonly attribute SupplierAdmin defaultSupplierAdmin;
ConsumerAdmin NewForConsumers(in InterFilterGroupOperator op,
out AdminID id );
SupplierAdmin NewForSuppliers(in InterFilterGroupOperator op,
out AdminID id );
ConsumerAdmin GetConsumerAdmin( in AdminID id )
raises ( AdminNotFound );
SupplierAdmin GetSupplierAdmin( in AdminID id )
raises ( AdminNotFound );
AdminIDSeq GetAllConsumerAdmins();
AdminIDSeq GetAllSupplierAdmins();
}; // IEventChannel
typedef long ChannelID;
typedef sequence ChannelIDSeq;
exception ChannelNotFound{};
interface IEventChannelFactory
{
IEventChannel CreateChannel(in IMSNotification::QoSProperties intitialQos,
in IMSNotification::AdminProperties initialAdmin,
out ChannelID id )
raises( IMSNotification::UnusupportedQoS,
IMSNotification::UnsupportedAdmin );
ChannelIDSeq GetAllChannels();
EventChannel GetEventChannel ( in ChannelID id )
raises( ChannelNotFound );
}; // IEventChannelFactory
}; // IMSNotifyChannelAdmin
#endif // _NOTIFYCHANNELADMIN_IDL_
#ifndef _NOTIFYFILTER_IDL_
#define _NOTIFYFILTER_IDL_
module IMSNotifyFilter
{
typedef long ConstraintID;
struct ConstraintExp
{
IMSNotification::EventTypeSeq eventTypes;
string constraintExpr;
};
typedef sequence ConstraintIDSeq;
typedef sequence ConstraintExpSeq;
struct ConstraintInfo
{
ConstraintExp constraintExpression;
ConstraintID constraintId;
};
typedef sequence ConstraintInfoSeq;
struct MappingConstraintPair
{
ConstraintExp constraintExpression;
any resultToSet;
};
typedef sequence MappingConstraintPairSeq;
struct MappingConstraintInfo
{
ConstraintExp constraintExpression;
ConstraintID constraintId;
any value;
};
typedef sequence MappingConstraintInfoSeq;
typedef long CallbackID;
typedef sequence CallbackIDSeq;
exception UnsupportedFilterableData {};
exception InvalidGrammar {};
exception InvalidConstraint { ConstraintExp constr; };
exception DuplicateConstraintID { ConstraintID id; };
exception ConstraintNotFound { ConstraintID id; );
exception CallbackNotFound {};
exception InvalidValue { ConstraintExp constr; any value; };
interface IFilter
{
readonly attribute string constraintGrammar;
ConstraintInfoSeq AddConstraints( in ConstraintExpSeq constraintList )
raises( InvalidConstraint );
void ModifyConstraints( in ConstraintIDSeq delList,
in ConstraintInfoSeq modifyList )
raises( InvalidConstraint, ConstraintNotFound );
ConstraintInfoSeq GetConstraints( in ConstraintIDSeq idList )
raises( ConstraintNotFound );
ConstraintInfoSeq GetAllConstraints();
void RemoveAllConstraints();
void Destroy();
boolean Match( in any filterableData )
raises( UnsupportedFilterableData );
boolean MatchStructured ( in IMSNotification::StructuredEvent filterableData )
raises( UnsupportedFilterableData );
boolean MatchTyped( in IMSTrading::PropertySeq filterableData )
raises( UnsupportedFilterableData );
CallbackID AttachCallback( in IMSNotifyComm::INotifySubscribe callback );
void DetachCallback( in CallbackID callback )
raises( CallbackNotFound );
CallbackIDSeq GetCallbacks();
}; // IFilter
interface IMappingFilter
{
readonly attribute string constraintGrammar;
readonly attribute CORBA::TypeCode valueType;
readonly attribute any defaultValue;
MappingConstraintInfoSeq AddMappingConstraints( in MappingConstraintPairSeq pairList )
raises( InvalidConstraint, InvalidValue );
void ModifyMappingConstraints(in ConstraintIDSeq delList,
in MappingConstraintInfoSeq modifyList )
raises( InvalidConstraint,
InvalidValue,
ConstraintNotFound );
MappingConstraintInfoSeq GetAllMappingConstraints();
void RemoveAllMappingConstraints();
void Destroy();
boolean Match( in any filterableData,
out any resultToSet )
raises( UnsupportedFilterableData );
boolean MatchStructured( in IMSNotification::StructuredEvent filterableData,
out any resultToSet )
raises( UnsupportedFilterableData );
boolean MatchTyped(in IMSTrading::PropertySeq filterableData,
out any resultToSet )
raises( UnsupportedFilterableData );
}; // IMappingFilter
interface IFilterFactory
{
Filter CreateFilter( in string constraintGrammar )
raises( InvalidGrammar );
IMappingFilter CreateMappingFilter(in string constraintGrammar,
in any defaultValue )
raises( InvalidGrammar );
}; // IFilterFactory
typedef long FilterID;
typedef sequence FilterIDSeq;
exception FilterNotFound {};
interface IFilterAdmin
{
FilterID AddFilter ( in Filter newFilter );
void RemoveFilter ( in FilterID filter )
raises( FilterNotFound );
Filter GetFilter( in FilterID filter )
raises( FilterNotFound );
FilterIDSeq GetAllFilters();
void RemoveAllFilters();
}; // IFilterAdmin
}; // IMSNotifyFilter
#endif // _NOTIFYFILTER_IDL_
#ifndef _TYPEDNOTIFYCHANNELADMIN_IDL_
#define _TYPEDNOTIFYCHANNELADMIN_IDL_
module IMSTypedNotifyChannelAdmin
{
typedef string Key;
interface ITypedProxyPushConsumer : IMSNotifyChannelAdmin::IProxyConsumer,
IMSNotifyComm::INotifyPublish,
IMSTypedEventComm::ITypedPushConsumer
{
void ConnectTypedPushSupplier( in IMSEventComm::IPushSupplier pushSupplier )
raises( IMSEventChannelAdmin::AlreadyConnected );
}; // ITypedProxyPushConsumer
interface ITypedProxyPullSupplier : IMSNotifyChannelAdmin::IProxySupplier,
IMSNotifyComm::INotifySubscribe,
IMSTypedEventComm::ITypedPullSupplier
{
void ConnectTypedPullConsumer( in IMSEventComm::PullConsumer pullConsumer )
raises( IMSEventChannelAdmin::AlreadyConnected );
}; // ITypedProxyPullSupplier
interface ITypedProxyPullConsumer : IMSNotifyChannelAdmin::IProxyConsumer,
IMSNotifyComm::INotifyPublish,
IMSEventComm::IPullConsumer
{
void ConnectTypedPullSupplier( in IMSTypedEventComm::ITypedPullSupplier pullSupplier )
raises( IMSEventChannelAdmin::AlreadyConnected,
IMSEventChannelAdmin::TypeError );
}; // ITypedProxyPullConsumer
interface ITypedProxyPushSupplier : IMSNotifyChannelAdmin::IProxySupplier,
IMSNotifyComm::INotifySubscribe,
IMSEventComm::IPushSupplier
{
void ConnectTypedPushConsumer( in IMSTypedEventComm::ITypedPushConsumer pushConsumer )
raises( IMSEventChannelAdmin::AlreadyConnected,
IMSEventChannelAdmin::TypeError );
void SuspendConnection()
raises( IMSNotifyChannelAdmin::ConnectionAlreadyInactive );
void ResumeConnection()
raises( IMSNotifyChannelAdmin::ConnectionAlreadyActive );
}; // ITypedProxyPushSupplier
interface ITypedConsumerAdmin : IMSNotifyChannelAdmin::IConsumerAdmin,
IMSTypedEventChannelAdmin::ITypedConsumerAdmin
{
ITypedProxyPullSupplier ObtainTypedNotificationPullSupplier( in Key supportedInterface,
out IMSNotifyChannelAdmin::ProxyID proxyId )
raises( IMSTypedEventChannelAdmin::InterfaceNotSupported,
IMSNotifyChannelAdmin::AdminLimitExceeded );
ITypedProxyPushSupplier ObtainTypedNotificationPushSupplier( in Key usesInterface,
out IMSNotifyChannelAdmin::ProxyID proxyId )
raises( IMSTypedEventChannelAdmin::NoSuchImplementation,
IMSNotifyChannelAdmin::AdminLimitExceeded );
}; // ITypedConsumerAdmin
interface ITypedSupplierAdmin: IMSNotifyChannelAdmin::ISupplierAdmin,
IMSTypedEventChannelAdmin::ITypedSupplierAdmin
{
ITypedProxyPushConsumer ObtainTypedNotificationPushConsumer( in Key supportedInterface,
out IMSNotifyChannelAdmin::ProxyID proxyId )
raises( IMSTypedEventChannelAdmin::InterfaceNotSupported,
IMSNotifyChannelAdmin::AdminLimitExceeded );
ITypedProxyPullConsumer ObtainTypedNotificationPullConsumer( in Key usesInterface,
out IMSNotifyChannelAdmin::ProxyID proxyId )
raises( IMSTypedEventChannelAdmin::NoSuchImplementation,
IMSNotifyChannelAdmin::AdminLimitExceeded );
}; // ITypedSupplierAdmin
interface ITypedEventChannel : IMSNotifyChannelAdmin::IEventChannel,
IMSTypedEventChannelAdmin::ITypedEventChannel
{
ITypedConsumerAdmin NewForTypedNotificationConsumers(
in IMSNotifyChannelAdmin::InterFilterGroupOperator op,
out IMSNotifyChannelAdmin::AdminID id );
ITypedSupplierAdmin NewForTypedNotificationSuppliers(
in IMSNotifyChannelAdmin::InterFilterGroupOperator op,
out IMSNotifyChannelAdmin::AdminID id );
}; // ITypedEventChannel
interface ITypedEventChannelFactory : IMSNotifyChannelAdmin::IEventChannelFactory
{
ITypedEventChannel CreateTypedChannel( in IMSNotification::QoSProperties initialQoS,
in IMSNotification::AdminProperties initialAdmin,
out IMSNotifyChannelAdmin::ChannelID id )
raises( IMSNotification::UnsupportedQoS,
IMSNotification::UnsupportedAdmin );
}; // ITypedEventChannelFactory
}; // IMSTypedNotifyChannelAdmin
#endif // _TYPEDNOTIFYCHANNELADMIN_IDL_
DCOM IDL
Relationship Service Interfaces
Origin of Interfaces
The following information is based entirely on the Object Management Groups specification of the Common Object Services Relationship Service. The end of this section contains the actual IMS content model objects, which are derived versions of Nodes, Relationships, and Graph Traversals. The only changes that have been made, other than the addition of IMS context information, is the harmonization of interface signatures with the rest of the IMS and the possible removal of some low level CORBA dependencies.
The Base Relationship Model
The base level of the Relationship Service defines interfaces that support relationships between two or more CORBA objects. Objects that participate in a relationship are called related objects. Relationships that share the same semantics form relationship types. A relationship is an instance of a relationship type and has an identity. Each related object is connected with the relationship via a role. Roles are objects which characterize a related objects participation in a relationship type. Role types are used for expressing the roles characteristics by an IDL interface. Cardinality represents the number of relationship instances connected to a role. Degree represents the number of roles in a relationship. All characteristics are expressed by corresponding IDL interfaces. Relationship and role types are built by subtyping the Relationship and Role interfaces.
Figure 9-6 gives a graphical representation of a simple relationship type. It illustrates that documents reference books. Documents are in the ReferencesRole and books are in the ReferencedByRole. Documents, reference, the roles and books are all types; there are interfaces (written in OMG IDL) for all five.
INSERT FIGURE 9-6
Figure 9-7, on the other hand, gives a graphical representation of an instance of a relationship type. It illustrates that my document, an instance of Document, references War and Peace, an instance of Book.1
INSERT FIGURE 9-7
Relationship Attributes and Operations
Relationships may have attributes and operations. For example, the reference relationship of Figure 9-6 has an attribute indicating the date the reference from the document to the book was established.
Rationale
If relationships are not allowed to define attributes and operations, they will have to be assigned to one of the related objects. This approach is prone to misunderstandings and inconsistencies. The approach to define an artificial related object, which then carries the attributes, is equally unsatisfactory.
The date attribute of the example of Figure 9-7 is clearly an attribute of the relationship, not one of related objects. It cannot be an attribute of my document since my document can reference many books on different dates. Similarly, it cannot be an attribute of War and Peace since War and Peace can be referenced by many books on different dates.
Higher Degree Relationships
The Reference relationship in Figure 9-6 is a binary relationship; that is, it is defined by two roles. The Relationship Service can also support relationships with more than two roles. The fact that three or more related objects may be part of a relationship can be expressed directly by means of the same concept as in the binary case. The degree represents the number of roles in a relationship. The Relationship Service supports higher degree relationships, that is relationships with degree greater than two. Figure 9-8 shows a ternary check out relationship between books, libraries and persons. The semantics of this relationship is that a person borrows a book from a library. The relationship also defines an attribute that indicates the date when the book is due to be returned by the person to the library.
INSERT FIGURE 9-8 TERNARY ...
Rationale
The Relationship Service represents higher degree relationships directly. It clearly defines the number of expected related objects as well as other integrity constraints. It is more readable, more understandable and easier to enforce consistency constraints for related objects with a direct representation than with alternative representations that simulate higher degree relationships using a set of binary relationships. When simulating higher degree relationships, the relationship information is spread over multiple object and relationship type definitions, as are the corresponding integrity constraints.
Figure 9-9 shows an alternative representation of the ternary relationship from Figure 9-8 using binary relationships. Note that the first representation is not equivalent to that of Figure 9-8 since cardinalities and other integrity constraints cannot be expressed correctly in this alternative representation.
INSERT FIGURE 9-9 UNSATIFACTORY.
Figure 9-10 illustrates a second alternative representation of the ternary relationship of Figure 9-8. It uses an additional (artificial) related object type. This representation is equivalent to Figure 9-8 if Check-out is constrained to participate in exactly one instance of each of the three binary relationship types. However, this alternative needs three relationship types and one additional related object type (Check-out) instead of only one relationship type, and therefore is much more complex and harder to capture when compared to the representation using one relationship type with degree 3.
INSERT FIGURE 9-10 ANOTHER UNSATIS..
Since the Relationship Service supports higher order relationships directly, the user of the service need not resort to the unsatisfactory representations using binary relationships of Figure 9-9 and Figure 9-10.
Operations
The base level of the Relationship Service provides operations to:
Create role and relationship objects
Navigate relationships
Destroy roles and relationships
Iterate over the relationships in which a role participates
Creation
Roles are constructed independently using a role factory. Roles represent an existing related object that is passed as a parameter to the RoleFactory::create operation. When creating a new role object, the type of the related object can be checked by the factory. The minimum and maximum cardinality, e.g. the minimal and the maximal number of relationship instances to which the new role object may be connected, are indicated by attributes on the factory.
Figure 9-11 illustrates a newly created role.
Figure 9-11 Creating a role for an object
A new relationship is created by passing a sequence of named roles to a factory for the relationship. The expected degree and role types for the new relationship are indicated by attributes on the factory. During the creation of the new relationship, the role types and the maximum cardinality can be checked. Duplicate role names are not allowed since the names are used to distinguish the roles in the scope of the relationship. When creating a relationship, the factory creates links between the roles and the relationship using the link operation on the role. Figure 9-12 illustrates a fully established binary relationship.1
Figure 9-12 A fully established binary relationship
Navigation
Figure 9-12 illustrates the navigational functionality of a relationship. In particular,
a relationship defines an attribute that indicates a read-only attribute that indicates the named roles of the relationship,
a role defines a read-only attribute that indicates the related object that the role represents,
A role supports the get_other_role operation, that given a relationship object and a role name, returns the other role object,
A role supports the get_other_related_object operation, that given a relationship object and a role name, returns the related object that the named role represents in the relationship and
A role supports the get_relationships operation which returns the relationships in which the role participates.
Destruction
For both roles and relationship objects, the Relationship Services introduces a destroy operation. The destroy operation for relationship objects also destroys the links between the relationship and all of the role objects.
Consistency Constraints
For each role two cardinalities are defined: minimum and maximum.
The minimum cardinality indicates the minimum number of relationship instances in which a role must participate.
The maximum cardinality indicates the maximum number of relationship instances in which a role can participate. Maximum cardinality constraint can be checked when relationships are created. Note that the relationship mechanism cannot, by itself, enforce the minimum cardinality constraint. However, a role can be asked explicitly if it meets its minimum cardinality constraint using the check_minimum_cardinality operation.
Type integrity is preserved by CORBA mechanisms because related objects, roles and relationships are instances of CORBA object types. Type constraints can be checked when roles and relationships are created.
Implementation Strategies
Figure 9-12 illustrates the navigational functionality of a fully established binary relationship. There are a variety of implementation strategies possible. The get_other_role and the get_other_related_object operations can be:
Implemented by caching object references to other roles and related objects, or
Computed when needed using the relationship object.
The appropriate implementation strategy typically depends on distribution boundaries. If the roles and relationship objects are clustered, then only storing the values at the relationship object optimizes space. If, on the other hand, the roles and the related objects are clustered, caching object references to other roles and related objects at the roles allows the relationship to be efficiently navigated without involving a remote relationship object.
Role implementations that cache object references to other roles and related objects need not worry about updating the cache. Once the related objects and relationships are established, they cannot be changed.
The IMSObjectIdentity Module
CORBA: Common Object Request Broker Architecture and Specification does not define a notion of object identity for objects. The Relationship Service requires object identity for the objects it defines. As such, the Relationship Service assumes the IMSObjectIdentity module specified in Figure 9-13 . This is defined in a separate module; other Object Services may find this module to be generally useful.
The IIdentifiableObject Interface
Objects that support the IdentifiableObject interface implement an attribute of type ObjectIdentifier and the is_identical operation. This mechanism provides an efficient and convenient method of supporting object identity in a heterogeneous CORBA-based environment.
#ifndef _OBJECTIDENTITY_IDL_
#define _OBJECTIDENTITY_IDL_
module IMSObjectIdentity
{
typedef unsigned long ObjectIdentifier;
interface IdentifiableObject
{
readonly attribute ObjectIdentifier constant_random_id;
boolean is_identical (in IdentifiableObject other_object);
};
};
#endif // _OBJECTIDENTITY_IDL_
Figure 9-13 The IMSObjectIdentity Module
constant_random_id
Objects supporting the IdentifiableObject interface define an attribute of type ObjectIdentifier. The value of the attribute must not change during the lifetime of the object.
A typical client use of this attribute is as a key in a hash table. As such, the more randomly distributed the values are, the better.
The value of this attribute is not guaranteed to be unique; that is, another identifiable object can return the same value. However, if objects return different identifiers, clients can determine that two identifiable objects are not identical.
To determine if two identifiable objects are identical, the is_identical operation must be used.
is_identical
The is_identical operation returns true if the object and the other_object are identical. Otherwise, the operation returns false.
The IMSRelationships Module
The IMSRelationships module defines the interfaces of the base level RelationshipService. In particular, it defines
Relationship and Role interfaces to represent relationships and roles,
RelationshipFactory and RoleFactory interfaces to create relationships and roles
RelationshipIterator interface to enumerate the relationships in which a role participates
The IMSRelationships module is shown in Figure 9-14.
#ifndef _RELATIONSHIPS_IDL_
#define _RELATIONSHIPS_IDL_
#include
module IMSRelationships
{
interface RoleFactory;
interface RelationshipFactory;
interface Relationship;
interface Role;
interface RelationshipIterator;
typedef Object RelatedObject;
typedef sequence Roles;
typedef string RoleName;
typedef sequence RoleNames;
struct NamedRole {RoleName name; Role aRole;};
typedef sequence NamedRoles;
struct RelationshipHandle
{
Relationship the_relationship;
IMSObjectIdentity::ObjectIdentifier constant_random_id;
};
typedef sequence RelationshipHandles;
interface RelationshipFactory
{
struct NamedRoleType
{
RoleName name;
::CORBA::InterfaceDef named_role_type;
};
typedef sequence NamedRoleTypes;
readonly attribute ::CORBA::InterfaceDef relationship_type;
readonly attribute unsigned short degree;
readonly attribute NamedRoleTypes named_role_types;
exception RoleTypeError {NamedRoles culprits;};
exception MaxCardinalityExceeded {NamedRoles culprits;};
exception DegreeError {unsigned short required_degree;};
exception DuplicateRoleName {NamedRoles culprits;};
exception UnknownRoleName {NamedRoles culprits;};
Relationship create (in NamedRoles named_roles)
raises (RoleTypeError,
MaxCardinalityExceeded,
DegreeError,
DuplicateRoleName,
UnknownRoleName);
};
interface Relationship : IMSObjectIdentity::IdentifiableObject
{
exception CannotUnlink {Roles offending_roles;};
readonly attribute NamedRoles named_roles;
void destroy () raises(CannotUnlink);
};
interface Role
{
exception UnknownRoleName {};
exception UnknownRelationship {};
exception RelationshipTypeError {};
exception CannotDestroyRelationship {RelationshipHandles offenders;};
exception ParticipatingInRelationship {RelationshipHandles the_relationships;};
readonly attribute RelatedObject related_object;
RelatedObject get_other_related_object (in RelationshipHandle rel,
in RoleName target_name)
raises (UnknownRoleName,
UnknownRelationship);
Role get_other_role ( in RelationshipHandle rel,
in RoleName target_name)
raises (UnknownRoleName, UnknownRelationship);
void get_relationships (in unsigned long how_many,
out RelationshipHandles rels,
out RelationshipIterator iterator);
void destroy_relationships()
raises(CannotDestroyRelationship);
void destroy() raises(ParticipatingInRelationship);
boolean check_minimum_cardinality ();
void link ( in RelationshipHandle rel,
in NamedRoles named_roles)
raises( RelationshipFactory::MaxCardinalityExceeded,
RelationshipTypeError);
void unlink (in RelationshipHandle rel)
raises (UnknownRelationship);
};
interface RoleFactory
{
exception NilRelatedObject {};
exception RelatedObjectTypeError {};
readonly attribute ::CORBA::InterfaceDef role_type;
readonly attribute unsigned long max_cardinality;
readonly attribute unsigned long min_cardinality;
readonly attribute sequence<::CORBA::InterfaceDef> related_object_types;
Role create_role (in RelatedObject related_object)
raises (NilRelatedObject, RelatedObjectTypeError);
};
interface RelationshipIterator
{
boolean next_one (out RelationshipHandle rel);
boolean next_n (in unsigned long how_many,
out RelationshipHandles rels);
void destroy ();
};
};
#endif // _RELATIONSHIPS_IDL_
Figure 9-14 The IMSRelationships Module
Example of Containment Relationships The example of Figure 9-15 is referred to throughout the following sections to describe roles and relationships. The figure represents two binary, one-to-many containment relationships between a document and a figure and a logo.
Figure 9-15 Two binary one-to-many containment relationships.
The IRelationshipFactory Interface
The RelationshipFactory interface defines an operation for creating an instance of a relationship among a set of related objects. The factory also defines two attributes that specify the degree and role types of the relationships it creates.
Creating a Relationship
The create operation creates a new instance of a relationship. The factory is passed a sequence of named roles that represent the related objects in the newly created relationship. The factory, in turn, informs the roles about the new relationship using the link operation described in section .
Roles implement maximum cardinality constraints. A role may refuse to participate in a new relationship because it would violate a cardinality constraint. In such a case, the MaxCardinalityExceeded exception is raised and the offending roles are returned in the exception.
The number of roles passed to the create operation must be the same as the value of the degree attribute. If not, the DegreeError exception is raised. Role names are used to associate each actual role object with one of the formal roles expected by the relationship to be created.
The set of role names passed to the create operation must be the same as the set of role names in the factorys named_role_types attribute. If not, the UnknowRoleName exception is raised, and the unrecognized names are returned in the exception. The sequence order of the named_roles parameter and the sequence order of the named_role_types need not correspond.
The type of each role passed to the create operation must be of the same type as the type indicated for the corresponding role name in the named_role_types attribute. If not, the RoleTypeError is raised and the offending roles are returned in the exception.
The names of the roles passed to the create operation must be unique within the scope of this relationship type. If not, the DuplicateRoleName exception is raised.
Example of Figure 9-15 The document and the figure were related, that is relationship B was created, by passing roles A and C to the create operation of the relationship factory. Similarly, the document and the logo were related by passing roles C and E to the relationship factory for relationship D.
Determining the Created Relationships Type
The relationship created by a factory may be a subtype of the Relationship interface. The rrelationship_type attribute indicates the actual types of the relationships created by the factory.
Determining the Degree of a Relationship Type
The degree attribute indicates the number of roles for the relationships created by the factory.
Example of Figure 9-15 The relationship factory for containment has a degree attribute whose value is 2 because containment is a binary relationship.
Determining Names and Types of the Roles of a Relationship Type
The named_role_types attribute indicates the required names and types of roles for the relationships created by the factory. NamedRoleTypes are defined as structures where the role type is given by the IMS::InterfaceDef for the role objects.
Example of Figure 9-15 The relationship factory for containment has an attribute whose value is a sequence of two CORBA::InterfaceDefs: one for ContainsRole and one for ContainedInRole.
The IRelationship Interface
The Relationship interface defines an attribute whose value is the named roles of the relationship and an operation to destroy the relationship.
Determining the Roles of a Relationship and Their Names
The named_roles attribute returns the roles of the relationship. The roles have the names that were indicated in the create operation defined by the
RelationshipFactory interface.
Example of Figure 9-15 Relationship B has an attribute whose value is a sequence . Similarly, relationship D has an attribute whose value is a sequence .
Destroying a Relationship
The destroy operation destroys the relationship between the objects. The roles are unlinked by the relationship implementation before it is destroyed. If roles cannot be unlinked, the CannotUnlink exception is raised and the roles that could not be unlinked are returned in the exception.
Example of Figure 9-15 If destroy is requested of relationship B, the unlink operation is requested of both roles A and C and the relationship B is destroyed.
The IRole Interface
The Role interface defines operations to:
navigate the relationship from one role to another,
enumerate the relationships in which the role participates,
destroy all relationships in which the role participates,
link a role to a newly created relationship and
unlink a role in the destruction process of a relationship and
destroy the role itself,
readonly attribute NamedRoles named_roles;
void destroy () raises(CannotUnlink);
Determining the Related Object That a Role Represents
The related_object attribute indicates the related object that the role represents. The related object that the role represents is specified as a parameter to the create operation defined by the RoleFactory interface.
Getting Another Related Object
The get_other_related_object operation navigates the relationship rel to the related object represented by the role named target_name. If the role does not know about a role named target_name, the UnknownRoleName exception is raised. If the role does not know about the relationship rel, the UnknownRelationship exception is raised.
Example of Figure 9-15 Assuming role A is named A, requesting get_other_related_object(B,A) of role C returns the figure. On the other hand, requesting get_other_related_object(D,E) of role C returns the logo.
Getting Another Role
The get_other_role operation navigates the relationship rel to the role named target_name. The role is returned. If the role does not know about a role named target_name for the relationship rel, the UnknownRoleName exception is raised. If the role does not know about the relationship rel, the UnknownRelationship exception is raised.
Example of Figure 9-15 Assuming role A is named A, requesting get_other_role(B,A) of role C returns role A. On the other hand, requesting get_other_role(D,E) of role C returns role E.
Getting All Relationships in Which a Role Participates
The get_relationships operation returns the relationships in which the role participates.
The size of the list is determined by the how_many argument. If there are more relationships than specified by the how_many argument, an iterator is created and returned with the additional relationships. If there are no more relationships, a nil object reference is returned for the iterator. (The RelationshipIterator interface is a standard iterator described in the next section. )
Example of Figure 9-15 Requesting get_relationships on role C would return the relationships B and D.
Destroying All Relationships in Which a Role Participates
The destroy_relationships operation destroys all relationships in which the role participates.
The destroy_relationships operation is semantically equivalent to requesting destroy of each relationship in which the role participates. The operation is not required to be implemented in that fashion.
If the destroy_relationships operation cannot destroy one of the relationships, then the CannotDestroyRelationship exception is raised and the relationships that could not be destroyed are returned in the exception.
Example of Figure 9-15 Requesting destroy_relationships of role A causes relationship B to be destroyed. On the other hand, requesting destroy_relationships of role C causes relationships B and D to be destroyed.
Destroying a Role
The destroy operation destroys the role. The role must not be participating in any relationships. If it is, the ParticipatingInRelationship exception is raised and the relationships in which the role participates are returned in the exception.
Example of Figure 9-15 Requesting destroy_role of role A destroys relationship B and role A.
Checking Minimum Cardinality of a Role
The check_minimum_cardinality operation returns true if a role satisfies its minimum cardinality constraints. Otherwise, the operation returns false.
Example of Figure 9-15 Requesting check_minimum_cardinality of role A would return true since it is participating in relationship B.
Linking a Role in a Newly Created Relationship
Note The link operation is not intended for general purpose clients that create, navigate and destroy relationships. Instead, it is an operation intended for implementations of the relationship factory create operation.
The link operation informs the role that a new relationship is being created. The role is passed a relationship and a set of named roles that represent related objects in the relationship.
A role can have a maximum cardinality, that is it may limit the number of relationships in which it participates. If the link request would cause the maximum to be exceeded, the MaxCardinalityExceeded exception is raised. If the type of the relationship does not agree with the relationship type that the role expects, the RelationshipTypeError exception is raised.
Example of Figure 9-15 When creating relationship B, the factory for B requested the link (B, A,C) operation on roles A and C. This allows roles A and C to support the navigation and administration operations for relationship B.
Removing a Role from a Relationship
Note The unlink operation is not intended for general purpose clients that create, navigate and destroy relationships. Instead, it is an operation intended for implementations of the relationship destroy operation.
The unlink operation causes the role to delete its record of the relationship. If the relationship passed as an argument is unknown to the role, the UnknownRelationship exception is raised.
Example of Figure 9-15 The implementation of the destroy operation on relationship B requests unlink(B) of roles A and C. This causes roles A and C to forget their participation in relationship B.
The IRoleFactory Interface
The RoleFactory interface defines attributes describing the roles that it creates and a single operation to create a role.
Creating a Role
The create_role operation creates a role for the related object passed as a parameter. A role must represent a related object. If a nil object reference is passed to the factory for the related object, the NilRelatedObject exception is raised. Role factories can restrict the type of objects the roles they create will represent. If the interface of the related object does not conform, the RelatedObjectTypeError exception is raised.
Example of Figure 9-15 Clients that created roles A, C and E used the create operation of factories that support the RoleFactory interface.
Determining the Created Roles Type
The role created by a factory may be a subtype of the Role interface. The role_type attribute indicates the actual types of the roles created by the factory.
Determining the Maximum Cardinality of a Role
The max_cardinality attribute indicates the maximum number of relationships in which a role (created by the factory) participates.
Example of Figure 9-15 The factory for role A returns 1, since a ContainedIn role can be in no more than one relationship. Attempts to add role A to more than one relationship result in MaxCardinalityExceeded exceptions. (See the create operation of the RelationshipFactory interface and the link operation of the Role interface.)
Determining the Minimum Cardinality of a Role
The min_cardinality attribute indicates the minimum number of relationships in which a role (created by the factory) participates.
Note, that unlike maximum cardinality, minimum cardinality cannot be enforced since roles will be below their minimum during relationship construction. Roles do support the check_minimum_cardinality operation to report if they are below their minimum.
Example of Figure 9-15 The factory for role A returns 1, since a ContainedIn role should be in one relationship.
Determining the Related Object Types for a Role
The factory creates roles that represent related objects in relationships. The related objects must support at least one of the interfaces indicated by the related_object_type attribute.
Example of Figure 9-15 The factory for role C returns the CORBA::InterfaceDef for a document.
The IRelationshipIterator Interface
The RelationshipIterator interface is returned by the get_relationships operation defined by the Role interface. It allows clients to iterate through any additional relationships in which the role participates.
next_one
The next_one operation returns the next relationship; if no more relationships exist, it returns false.
next_n
The next_n operation returns at most the requested number of relationships; if no more relationships exist, it returns false.
destroy
The destroy operation destroys the iterator.
9.4 Graphs of Related Objects
When objects are related using the Relationship Service, graphs of related objects are formed. This section focuses on how the Relationship Service supports graphs of related objects. We first describe the graph architecture supported by the service, describe support for traversing the graph and implementing compound operations and then specify the IMSGraphs module in detail.
Graphs are important for distributed, object-oriented applications. A few examples of graphs are:
Distributed Desktops
Folders and objects are connected together. Folders contain some objects and reference others. Folders may contain or reference other folders. The objects are distributed; they span multiple machines. The distributed desktop is a distributed graph.
Composed Applications
Applications are built out of existing objects that are connected together. An example of such a composed application is a shared white board. The composed application is a graph.
User Interface Hierarchies
Presentation objects visualize semantic objects for users. Presentations contain other presentation objects. For example, a window might contain a button. The user interface hierarchy is a graph.
Compound Documents
A compound document architecture allows graphics, animation, sound, video, etc. to be connected together to give the user the impression of a single document. The compound document is a graph.
9.4.1 Graph Architecture
A graph is a set of nodes and a set of edges, involving those nodes. Nodes are related objects that support the Node interface and edges are represented by the relationships that relate nodes.
Figure 9-3 on page 9-9 illustrates an example of a graph.
Figure 9-16 An example graph of related objects.
The folder, book, document, figure, library, person and logo are nodes in the graph. The edges of the graph are represented by the relationships:
containment: the folder and document,
containment: the document and the figure
containment: the document and the logo
reference: the figure and the logo
reference: the document and the book,
check_out: the book, the library and the person
The graph architecture supports multiple kinds of relationships. For example, in Figure 9-3, there are containment, reference and check_out relationships. The small circles depict roles for a reference relationship, the solid circles depict roles for a containment relationship and the shaded circles represent the roles of the check_out relationship.
A node can participate in more than one kind of relationship and thus have more than one role. In the example the document has three kinds of roles:
The ContainsRole
The ContainedInRole
The ReferencesRole
Nodes
Nodes are identifiable objects that support the Node interface. Nodes collect roles of a related object and the related object itself. A node enables standard traversals of graphs of related objects because it supports the following:
A readonly attribute defining all of its roles
An operation allowing roles of a particular type to be returned
Operations to add and remove roles
The Node interface can be inherited by related objects or an object implementing the Node interface can be instantiated and interposed in front of related objects. Interposition is particularly useful in these cases:
When connecting immutable objects, which are objects that are not aware of the Relationship Service
In order to traverse graphs of related objects without activating the related objects As such, the Node interface defines an attribute whose value is the related object it represents.
Traversing Graphs of Related Objects
The Relationship Service defines a traversal object that, given a starting node, produces a sequence of directed edges of the graph. A directed edge corresponds to a relationship. In particular, it consists of:
An instance of a relationship,
A starting node and a starting named role of the edge to indicate direction and
A sequence containing the remaining nodes and named roles. For binary relationships, there is a single remaining node and role. For n-ary relationships, there are n-1 remaining nodes and roles.
The traversal object works like an iterator, where directed edges are the items being returned. The traversal object, the nodes and the roles cooperate in traversing the graph. Through the operations of the Node interface, the node reveals its roles to the traversal object. Through the operations of the IMSGraphs::Role interface, a role reveals its directed edges to other nodes. (The IMSGraphs::Role interface defines an operation allowing a role to reveal directed edges.) In traversing a graph, the traversal object must detect and represent cycles, and determine the relevant nodes and edges.
Detecting and Representing Cycles
In order to terminate, a traversal must be able to detect a cycle in the graph. In the example of Figure 9-3, the document, the figure, and the logo form a cycle. To detect cycles in the graph, the traversal object depends on the fact that nodes are identifiable objects, that is they support the IdentifiableObject interface defined in section 9.3.6.
To represent cycles in the graph, the traversal object defines a scope of identifiers for the nodes and relationships in the graph. That is, a given traversal assigns identifiers to the nodes and relationships that are guaranteed to be unique within the scope of the traversal.
Determining the Relevant Nodes and Edges
A traversal begins at the starting node, emits directed edges and may continue to other related nodes. The traversal object is programmable in the criteria it uses for determining the edges to emit and the nodes to visit. The traversal object depends on a call-back object supporting the TraversalCriteria interface.
Given a node, the traversal criteria computes a sequence of directed edges to include in the traversal. For each edge, the traversal criteria can indicate whether the traversal should continue to an adjacent node. Based on the results of the traversal criteria, the traversal object emits edges and visits other nodes. The process continues until there are no more edges to emit and no more nodes to visit.
Three standard traversal modes are defined to allow clients flexibility in controlling the search order: depth first, breadth first, and best first. In order to understand the differences between the modes, consider that the traversal maintains an ordered list of the edges which have been produced by visiting nodes. This list initially contains the edges which result from visiting the root node. In each iteration the first edge is removed from the list to be returned and its destination nodes are visited. Depending upon the traversal mode, these edges are: inserted in the beginning of the list (depth first), appended to the end of the list (breadth first), or inserted into the list which is sorted by the edges weight (best first).
Compound Operations
Traversal objects are especially important in implementing compound operations on graphs of related objects. By compound operations, we mean operations that apply to some subset of the nodes and edges in the graph. Examples of compound operations include operations, such as copy, move, remove, externalize, print, and so forth.
Note The Relationship Service defines a framework for compound operations but does not define specific compound operations. The Life Cycle and the Externalization Service specifications define compound operations that depend on the Relationship Service.
A compound operation may be implemented either in one or two passes. A compound operation implemented in one pass traverses the graph itself and applies the operation as it proceeds.
A compound operation implemented in two passes uses the traversal object defined by the Relationship Service to determine the relevant nodes and detect and represent cycles. The second pass simply applies the operation to the results of the first pass. A compound operation implemented in two passes provides a TraversalCriteria object for the traversal service.
An Example Traversal Criteria
Consider a traversal of a graph with a traversal criteria object that uses propagation values defined by the relationships to determine whether to emit an edge and whether to proceed to another node. The traversal criteria is given a node by the traversal. The traversal criteria then requests propagation values from each of the nodes roles. Figure 9-17 illustrates a traversal of a graph using a traversal criteria for a compound copy operation. Using the propagation_for operation defined by CompoundLifeCycle::Role interface, the traversal criteria obtains the propagation value for the copy operation from each of the nodes roles.
Figure 9-17 A traversal of a graph for compound copy operation.
Propagation
Compound operations may propagate from one node to another depending on the semantics of the relationship between the nodes. The propagation semantics of a relationship depend on the direction the relationship is being traversed. A propagation value is either deep, shallow, inhibit or none.
Deep means that the operation is applied to the node, to the relationship and to the related objects. In the example of Figure 9-17, the propagation value for the copy operation is deep from the document to the logo; the copy propagates from the document to the logo across the containment relationship. The traversal criteria for copy that encounters a deep propagation value would instruct the traversal object to emit the edge and visit the logo.
Shallow means that the operation is applied to the relationship but not to the related objects. In the example of Figure 9-17, the propagation value for the copy operation from the logo to the document is shallow. The traversal criteria for copy that encounters a shallow propagation value would instruct the traversal object to emit the edge but the document is not visited.
None means that the operation has no effect on the relationship and no effect on the related objects. A traversal criteria that encounters a none propagation value would not return any edges and related nodes are not visited.
Figure 9-18 summarizes how deep, shallow and node propagation values affect nodes, roles and relationships.
Figure 9-18 How deep, shallow and none propagation values affect nodes, roles and relationships.
Inhibit means that the operation should not propagate to the node via any of the nodes roles. Inhibit is particularly meaningful for the remove operation to provide so-called existence-ensuring relationships. For more discussion of propagation values, see [1.].
9.4.5 The IMSGraphs Module
The IMSGraphs module defines the support for graphs of related objects. It defines the following interfaces:
TraversalFactory interface for creating traversal objects
Traversal interface for enumerating directed edges of a graph,
TraversalCriteria call-back interface to allow programmability of the traversal object
Node interface for collecting the roles of a related object
NodeFactory interface for creating nodes
Role interface to support traversals
The IMSGraphs module is shown in Figure 9-14
#ifndef _GRAPHS_IDL_
#define _GRAPHS_IDL_
#include
#include
module IMSGraphs
{
interface TraversalFactory;
interface Traversal;
interface TraversalCriteria;
interface Node;
interface NodeFactory;
interface Role;
interface EdgeIterator;
struct NodeHandle
{
Node the_node;
::IMSObjectIdentity::ObjectIdentifier constant_random_id;
};
typedef sequence NodeHandles;
struct NamedRole
{
Role the_role;
::IMSRelationships::RoleName the_name;
};
typedef sequence NamedRoles;
struct EndPoint
{
NodeHandle the_node;
NamedRole the_role;
};
typedef sequence EndPoints;
struct Edge
{
EndPoint from;
::IMSRelationships::RelationshipHandle the_relationship;
EndPoints relatives;
};
typedef sequence Edges;
enum PropagationValue {deep, shallow, none, inhibit};
enum Mode {depthFirst, breadthFirst, bestFirst};
interface TraversalFactory
{
Traversal create_traversal_on ( in NodeHandle root_node,
in TraversalCriteria the_criteria,
in Mode how);
};
interface Traversal
{
typedef unsigned long TraversalScopedId;
struct ScopedEndPoint
{
EndPoint point;
TraversalScopedId id;
};
typedef sequence ScopedEndPoints;
struct ScopedRelationship
{
::IMSRelationships::RelationshipHandle scoped_relationship;
TraversalScopedId id;
};
struct ScopedEdge
{
ScopedEndPoint from;
ScopedRelationship the_relationship;
ScopedEndPoints relatives;
};
typedef sequence ScopedEdges;
boolean next_one (out ScopedEdge the_edge);
boolean next_n (in short how_many,
out ScopedEdges the_edges);
void destroy ();
};
interface TraversalCriteria
{
struct WeightedEdge
{
Edge the_edge;
unsigned long weight;
sequence next_nodes;
};
typedef sequence WeightedEdges;
void visit_node(in NodeHandle a_node,
in Mode search_mode);
boolean next_one (out WeightedEdge the_edge);
boolean next_n (in short how_many,
out WeightedEdges the_edges);
void destroy();
};
interface Node: ::IMSObjectIdentity::IdentifiableObject
{
typedef sequence Roles;
exception NoSuchRole {};
exception DuplicateRoleType {};
readonly attribute ::IMSRelationships::RelatedObject related_object;
readonly attribute Roles roles_of_node;
Roles roles_of_type (in ::CORBA::InterfaceDef role_type);
void add_role (in Role a_role)
raises (DuplicateRoleType);
void remove_role (in ::CORBA::InterfaceDef of_type)
raises (NoSuchRole);
};
interface IResource: INode
{
IMSGroup::IGroup group;
IMSSession::ISession session;
};
interface NodeFactory
{
Node create_node (in Object related_object);
};
interface Role : ::IMSRelationships::Role
{
void get_edges ( in long how_many,
out Edges the_edges,
out EdgeIterator the_rest);
};
interface EdgeIterator
{
boolean next_one (out Edge the_edge);
boolean next_n ( in unsigned long how_many,
out Edges the_edges);
void destroy ();
};
};
#endif // _GRAPHS_IDL_
Figure 9-19 The IMSGraphs Module
The ITraversalFactory Interface
The TraversalFactory interface creates traversal objects. The Traversal interface is used by clients that want to traverse graphs of related objects according to some traversal criteria.
create_traversal_on
The create_traversal_on operation creates a traversal object starting at the root_node. The created traversal object uses the TraversalCriteria object to determine which directed edges to emit and which nodes to visit. The mode parameter indicates whether the traversal will proceed in a depth first, breadth first or best first fashion.
The ITraversal Interface
Traversal objects iterate through ScopedEdges of the graph according to the traversal criteria and the mode established when the traversal was created. The traversal also defines a scope for the nodes and edges it returns; that is, it assigns identifiers to the nodes and edges it returns. The identifiers are unique within the scope of a given traversal. ScopedEdges are given by the following structure: A ScopedEdge consists of a distinguished scoped end point, a scoped relationship and a sequence of scoped end points. The distinguished scoped end point indicates the direction of the edge. The scoped end point consists of a node, a role, and an identifier for the node that is unique within the scope of the traversal.
next_one
The next_one operation returns the next scoped edge; if no more scoped edges exist, it returns false.
next_n
The next_n operation returns at most the requested number of scoped edges.
destroy
The destroy operation destroys the traversal.
The ITraversalCriteria Interface
The TraversalCriteria interface is used by the traversal object to determine which edges to emit and which nodes to visit from a given node. The traversal criteria behaves like an iterator of weighted edges. Weighted edges are given by the following structure:
A WeightedEdge consists of an edge, a weight and a sequence of nodes indicating if the traversal should continue to the nodes. The weight is only meaningful for the best first traversal.
next_one
The next_one operation returns the next weighted edge; if no more weighted edges exist, it returns false.
next_n
The next_n operation returns at most the requested number of weighted directed edges.
destroy
The destroy operation destroys the traversal criteria.
visit_node
The visit_node operation establishes the node for which the traversal criteria will iterate and indicates the current search mode. As the traversal object traverses the graph, it visits nodes by requesting the visit_node operation of the traversal criteria, followed by next_one/next_n requests to obtain the outgoing edges from the node.
For depthFirst and breadthFirst modes, the weight field in the weighted edges is ignored. In the bestFirst mode, the weight value is utilized to order the traversals edges list which is sorted by this value in ascending order.
If weighted edges from a previous node remain when visit_node is requested, the traversal criteria discards the previous edges.
The INode Interface
The Node interface defines operations that are useful in navigating graphs of related objects. In particular, it defines:
Areadonly attribute giving all of the nodes roles
An operation allowing roles conforming to a particular type to be returned
Operations to add and remove roles
Roles are distinguished in nodes in the OMG IDL of their interfaces. A node cannot posses two roles where one role is a subtype of the other. This is precluded by the add_role operation.
A node can posses two or more roles that have a common supertype. The set of roles can be obtained by passing the common supertype to the roles_of_type operation.
related_object
The related_object attribute gives the related object that the node represents. This is useful when relating immutable objects.
roles_of_node
The roles_of_node attribute gives all of the nodes roles.
roles_of_type
The roles_of_type operation returns the nodes roles that conform to the role_type parameter. A role conforms to role_type if its interface is the same or is a subtype of role_type.
add_role
The add_role operation adds a role to the node. If the node posses a role of the same type, a supertype or a subtype of a_role, the DuplicateRoleType exception is raised.
remove_role
The remove_role operation removes all the roles that conform to the of_type parameter. If no roles conform to the of_type parameter, the NoSuchRole exception is raised.
The INodeFactory Interface
The NodeFactory interface defines a single operation for creating nodes.
create_node
The create_node operation creates a node whose related_object attribute is initialized to the related_object parameter.
The IRole Interface
The IMSGraphs::Role interface extends the IMSRelationships::Role interface with a single operation to return a roles view of its relationships. The roles view of a relationship is given by the following Edge structure:
The edge structure is defined by an end point, a relationship and the other end points. The from end point is the role and its related object.
get_edges
The get_edges operation returns the edges in which the role participates. The size of the list is determined by the how_many argument. If there are more edges than specified by the how_many argument, an iterator is created and returned. If there are no more edges, a nil object reference is returned for the iterator.
The IEdgeIterator Interface
The EdgeIterator interface is returned by the get_edges operation defined by the IMSGraphs::Role interface. It allows clients to iterate through any additional relationships in which the role participates.
next_one
The next_one operation returns the next edge; if no more edges exist, it returns false.
next_n
The next_n operation returns at most the requested number of edges.
destroy
The destroy operation destroys the iterator.
Specific Relationships
The Relationship Service defines two important relationships, containment and reference as part of its specification. The example used throughout this specification has been in terms of these two relationships.
Containment and Reference
Containment is a one-to-many relationship. A container can contain many containees; a containee is contained by one container. Reference, on the other hand, is a many-to-many relationship. An object can reference many objects; an object can be referenced by many objects.
Containment and reference are examples of relationships. However, since containment and reference are very common relationships, the Relationship Service defines them as standard.
Containment is defined by interfaces for a relationship and two roles: the IMSContainment::Relationship interface, the IMSContainment::ContainsRole interface, and the IMSContainment::ContainedInRole interface. Relationship is a subtype of IMSRelationships::Relationship and ContainedInRole and ContainsRole are subtypes of IMSGraphs::Role.
Similarly, reference is defined by interfaces for a relationship and two roles: the IMSReference::Relationship interface, the IMSReference::ReferencesRole interface, and the IMSReference::ReferencedByRole interface. Relationship is a subtype of IMSRelationships::Relationship and ReferencesRole and ReferencedByRole are subtypes of IMSGraphs::Role.
The IMSContainment Module
The IMSContainment module is shown in Figure 9-14.
#ifndef _CONTAINMENT_IDL_
#define _CONTAINMENT_IDL_
#include
module IMSContainment
{
interface Relationship : ::IMSRelationships::Relationship {};
interface ContainsRole : ::IMSGraphs::Role {};
interface ContainedInRole : ::IMSGraphs::Role {};
};
#endif _CONTAINMENT_IDL
Figure 9-20 The IMSContainment Module
The IMSContainment module does not define new operations. It introduces new IDL types to represent containment. Although it does not add any new operations, it refines the semantics of these attributes and operations:
RelationshipFactory attributeValueRelationship_typeIMSContainment::RelationshipDegree2Named_role_typesContainsRole, IMSContainment::ContainsRole;
ContainedInRole, IMSContainment::ContainedInRole
The IMSRelationships::RelationshipFactory::create operation will raise DegreeError if the number of roles passed as arguments is not 2. It will raise RoleTypeError if the roles are not IMSContainment::ContainsRole and IMSContainment::ContainedInRole. It will raise MaxCardinalityExceeded if the IMSContainment::ContainedInRole is already participating in a relationship.
RoleFactory attribute for ContainsRoleValueRole_typeIMSContainment::ContainsRoleMaximum_cardinalityUnboundedMinimum_cardinality0Related_object_typesIMSGraphs::NodeThe IMSRelationships::RoleFactory::create_role operation will raise the RelatedObjectTypeError if the related object passed as a parameter does not support the IMSGraphs::Node interface. The IMSRelationships::RoleFactory::link operation will raise RelationshipTypeError if the rel parameter does not conform to the IMSContainment::Relationship interface.
RoleFactory attribute for ContainedInRoleValueRole_typeIMSContainment::ContainedInRoleMaximum_cardinality1Minimum_cardinality1Related_object_typesIMSGraphs::Node
The IMSRelationships::RoleFactory::create_role operation will raise the RelatedObjectTypeError if the related object passed as a parameter does not support the IMSGraphs::Node interface. The IMSRelationships::RoleFactory::link operation will raise RelationshipTypeError if the rel parameter does not conform to the IMSContainment::Relationship interface. The IMSRelationships::RoleFactory::link operation will raise MaxCardinalityExceeded if it is already participating in a containment relationship.
The IMSReference Module
The IMSReference module is given in Figure 9-21.
#ifndef _REFERENCE_IDL_
#define _REFERENCE_IDL_
#include
module IMSReference
{
interface Relationship : ::IMSRelationships::Relationship {};
interface ReferencesRole : IMSGraphs::Role {};
interface ReferencedByRole : ::IMSGraphs::Role {};
};
#endif _REFERENCE_IDL_
Figure 9-21 The IMSReference Module
The IMSReference module does not define new operations. It introduces new IDL types to represent reference. Although it does not add any new operations, it refines the semantics of these attributes and operations:
RelationshipFactory attributeValueRelationship_typeIMSReference::RelationshipDegree2Named_role_typesReferencesRole, IMSReference::ReferencesRole;
ReferencedByRole, CoReference::ReferencedByRoleThe IMSRelationships::RelationshipFactory::create operation will raise DegreeError if the number of roles passed as arguments is not 2. It will raise RoleTypeError if the roles are not IMSReference::ReferencesRole and IMSReference::ReferencedByRole.
RoleFactory attribute for ReferencesRoleValueRole_typeIMSReference::ReferencesRoleMaximum_cardinalityUnboundedMinimum_cardinality0Related_object_typesIMSGraphs::NodeThe IMSRelationships::RoleFactory::create_role operation will raise the RelatedObjectTypeError if the related object passed as a parameter does not support the IMSGraphs::Node interface. The IMSRelationships::RoleFactory::link operation will raise RelationshipTypeError if the rel parameter does not conform to the IMSReference::Relationship interface.
RoleFactory attribute for ReferencedByRoleValueRole_typeIMSReference::ReferencedByRoleMaximum_cardinalityUnboundedMinimum_cardinality0Related_object_typesIMSGraphs::NodeThe IMSRelationships::RoleFactory::create_role operation will raise the RelatedObjectTypeError if the related object passed as a parameter does not support the IMSGraphs::Node interface. The IMSRelationships::RoleFactory::link operation will raise RelationshipTypeError if the rel parameter does not conform to the IMSRelationship::Relationship interface.
References
1. James Rumbaugh, Controlling Propagation of Operations using Attributes on
Relations. OOPSLA 1988 Proceedings, pg. 285-296.
2. James Rumbaugh, Michael Blaha, William Premerlani, Frederick Eddy and William
Lorensen, Object-oriented Modeling and Design. Prentice Hall, 1991.
CORBA IDL
#ifndef _OBJECTIDENTITY_IDL_
#define _OBJECTIDENTITY_IDL_
module IMSObjectIdentity
{
typedef unsigned long ObjectIdentifier;
interface IdentifiableObject
{
readonly attribute ObjectIdentifier constant_random_id;
boolean is_identical (in IdentifiableObject other_object);
};
};
#ifndef _RELATIONSHIPS_IDL_
#define _RELATIONSHIPS_IDL_
#include
module IMSRelationships
{
interface RoleFactory;
interface RelationshipFactory;
interface Relationship;
interface Role;
interface RelationshipIterator;
typedef Object RelatedObject;
typedef sequence Roles;
typedef string RoleName;
typedef sequence RoleNames;
struct NamedRole {RoleName name; Role aRole;};
typedef sequence NamedRoles;
struct RelationshipHandle
{
Relationship the_relationship;
IMSObjectIdentity::ObjectIdentifier constant_random_id;
};
typedef sequence RelationshipHandles;
interface RelationshipFactory
{
struct NamedRoleType
{
RoleName name;
::CORBA::InterfaceDef named_role_type;
};
typedef sequence NamedRoleTypes;
readonly attribute ::CORBA::InterfaceDef relationship_type;
readonly attribute unsigned short degree;
readonly attribute NamedRoleTypes named_role_types;
exception RoleTypeError {NamedRoles culprits;};
exception MaxCardinalityExceeded {NamedRoles culprits;};
exception DegreeError {unsigned short required_degree;};
exception DuplicateRoleName {NamedRoles culprits;};
exception UnknownRoleName {NamedRoles culprits;};
Relationship create (in NamedRoles named_roles)
raises (RoleTypeError,
MaxCardinalityExceeded,
DegreeError,
DuplicateRoleName,
UnknownRoleName);
};
interface Relationship : IMSObjectIdentity::IdentifiableObject
{
exception CannotUnlink {Roles offending_roles;};
readonly attribute NamedRoles named_roles;
void destroy () raises(CannotUnlink);
};
interface Role
{
exception UnknownRoleName {};
exception UnknownRelationship {};
exception RelationshipTypeError {};
exception CannotDestroyRelationship {RelationshipHandles offenders;};
exception ParticipatingInRelationship {RelationshipHandles the_relationships;};
readonly attribute RelatedObject related_object;
RelatedObject get_other_related_object (in RelationshipHandle rel,
in RoleName target_name)
raises (UnknownRoleName,
UnknownRelationship);
Role get_other_role ( in RelationshipHandle rel,
in RoleName target_name)
raises (UnknownRoleName, UnknownRelationship);
void get_relationships (in unsigned long how_many,
out RelationshipHandles rels,
out RelationshipIterator iterator);
void destroy_relationships()
raises(CannotDestroyRelationship);
void destroy() raises(ParticipatingInRelationship);
boolean check_minimum_cardinality ();
void link ( in RelationshipHandle rel,
in NamedRoles named_roles)
raises( RelationshipFactory::MaxCardinalityExceeded,
RelationshipTypeError);
void unlink (in RelationshipHandle rel)
raises (UnknownRelationship);
};
interface RoleFactory
{
exception NilRelatedObject {};
exception RelatedObjectTypeError {};
readonly attribute ::CORBA::InterfaceDef role_type;
readonly attribute unsigned long max_cardinality;
readonly attribute unsigned long min_cardinality;
readonly attribute sequence<::CORBA::InterfaceDef> related_object_types;
Role create_role (in RelatedObject related_object)
raises (NilRelatedObject, RelatedObjectTypeError);
};
interface RelationshipIterator
{
boolean next_one (out RelationshipHandle rel);
boolean next_n (in unsigned long how_many,
out RelationshipHandles rels);
void destroy ();
};
};
#endif // _RELATIONSHIPS_IDL_
#ifndef _GRAPHS_IDL_
#define _GRAPHS_IDL_
#include
#include
module IMSGraphs
{
interface TraversalFactory;
interface Traversal;
interface TraversalCriteria;
interface Node;
interface NodeFactory;
interface Role;
interface EdgeIterator;
struct NodeHandle
{
Node the_node;
::IMSObjectIdentity::ObjectIdentifier constant_random_id;
};
typedef sequence NodeHandles;
struct NamedRole
{
Role the_role;
::IMSRelationships::RoleName the_name;
};
typedef sequence NamedRoles;
struct EndPoint
{
NodeHandle the_node;
NamedRole the_role;
};
typedef sequence EndPoints;
struct Edge
{
EndPoint from;
::IMSRelationships::RelationshipHandle the_relationship;
EndPoints relatives;
};
typedef sequence Edges;
enum PropagationValue {deep, shallow, none, inhibit};
enum Mode {depthFirst, breadthFirst, bestFirst};
interface TraversalFactory
{
Traversal create_traversal_on ( in NodeHandle root_node,
in TraversalCriteria the_criteria,
in Mode how);
};
interface Traversal
{
typedef unsigned long TraversalScopedId;
struct ScopedEndPoint
{
EndPoint point;
TraversalScopedId id;
};
typedef sequence ScopedEndPoints;
struct ScopedRelationship
{
::IMSRelationships::RelationshipHandle scoped_relationship;
TraversalScopedId id;
};
struct ScopedEdge
{
ScopedEndPoint from;
ScopedRelationship the_relationship;
ScopedEndPoints relatives;
};
typedef sequence ScopedEdges;
boolean next_one (out ScopedEdge the_edge);
boolean next_n (in short how_many,
out ScopedEdges the_edges);
void destroy ();
};
interface TraversalCriteria
{
struct WeightedEdge
{
Edge the_edge;
unsigned long weight;
sequence next_nodes;
};
typedef sequence WeightedEdges;
void visit_node(in NodeHandle a_node,
in Mode search_mode);
boolean next_one (out WeightedEdge the_edge);
boolean next_n (in short how_many,
out WeightedEdges the_edges);
void destroy();
};
interface Node: ::IMSObjectIdentity::IdentifiableObject
{
typedef sequence Roles;
exception NoSuchRole {};
exception DuplicateRoleType {};
readonly attribute ::IMSRelationships::RelatedObject related_object;
readonly attribute Roles roles_of_node;
Roles roles_of_type (in ::CORBA::InterfaceDef role_type);
void add_role (in Role a_role)
raises (DuplicateRoleType);
void remove_role (in ::CORBA::InterfaceDef of_type)
raises (NoSuchRole);
};
interface IResource: INode
{
IMSGroup::IGroup group;
IMSSession::ISession session;
};
interface NodeFactory
{
Node create_node (in Object related_object);
};
interface Role : ::IMSRelationships::Role
{
void get_edges ( in long how_many,
out Edges the_edges,
out EdgeIterator the_rest);
};
interface EdgeIterator
{
boolean next_one (out Edge the_edge);
boolean next_n ( in unsigned long how_many,
out Edges the_edges);
void destroy ();
};
};
#ifndef _CONTAINMENT_IDL_
#define _CONTAINMENT_IDL_
#include
module IMSContainment
{
interface Relationship : ::IMSRelationships::Relationship {};
interface ContainsRole : ::IMSGraphs::Role {};
interface ContainedInRole : ::IMSGraphs::Role {};
};
#endif _CONTAINMENT_IDL
#ifndef _REFERENCE_IDL_
#define _REFERENCE_IDL_
#include
module IMSReference
{
interface Relationship : ::IMSRelationships::Relationship {};
interface ReferencesRole : IMSGraphs::Role {};
interface ReferencedByRole : ::IMSGraphs::Role {};
};
#endif _REFERENCE_IDL_
DCOM IDL
Property Service Interface
Origin of Interfaces
The following information is based entirely on World Wide Web Consortiums ( W3C ) Document Object Model. The only changes that have been made, other than the addition of IMS context information, is the harmonization of interface signatures with the rest of the IMS and the possible removal of some low level W3C dependencies.
Interface Descriptions
Module Property
The IProperty Interface
The IProperty interface allows an object to maintain a dynamically associated property set. The contents of this property set does not change the fundamental type of the object it is attached to. This interface carries the features of simple get/set/add property methods as well as the RDF property methods being developed by the W3C. This will allow an object to carry arbitrarily complex dynamic properties. This is especially usefull for attaching the value of Metadata to an instance of the Metadata interface. Every instance of Metadata could include a different schema of data, but it is still of the type Metadata.
mUser
This is a reference to the IMSUser that owns this PersonalData
GetProperty
This method returns a named property.
SetProperty
This method sets a named property. If the property already exists, the implementation of the method must update the existing property.
AddProperty
This method adds the named property. The property is always added as new, regardless if there is already a property of the same name. In this case there will end up two properties named the same.
Parse
This method parses an XML only stream, or an RDF description expressed in XML, into a Document object which can then be manipulated via the methods exposed by the IDocument Interface.
Module Document
This module contains the W3C Document Object Model. This model is being adopted by the IMS for the manipulation of complex property sets. Both the Metadata and the Property interfaces utilize this module.
The IAttribute Interface
The Attribute object represents an attribute in an Element object. Typically the allowable values for the attribute are defined in a document type definition.
value
The children of this Node define the effective value of this attribute. ( The attribute's effective value is determined as follows: if this attribute has been explicitly assigned any value, that value is the attribute's effective value; otherwise, if there is a declaration for this attribute, and that declaration includes a default value, then that default value is the attribute's effective value; otherwise, the attribute has no effective value. ) Note, in particular, that an effective value of the null string would be returned as a Text node instance whose toString method will return a zero length string ( as will toString invoked directly on this Attribute instance). If the attribute has no effective value, then this method will return null. Note the toString method on the Attribute instance can also be used to retrieve the string version of the attribute's value(s). There can be multiple objects defined as the value of an attribute because the raw attribute value can contain entity references. Thus the value of the attribute could be represented by a single Text node, ( and always will in HTML ) or a series of Text nodes interspersed with EntityReference nodes ( in XML ).
specified
If this attribute was explicitly given a value in the original document, this will be true; otherwise it will be false.
GetName
Returns the name of this attribute.
ToString
Returns the value of the attribute as a string. Character and general entity references will have been replaced with their values in the returned string.
The IAttributeDefinition interface
The IAttributeDefinition interface is used to access information about a particular attribute definition on a given element. Objects supporting this interface are available from the ElementDefinition object through the attributeDefinitions attribute.
name
The name of the attribute.
StringList
This list of tokens that are allowed as values.
declaredType
This attribute indicates the type of values the attribute may contain. Taken from the first set of constant declarations in this interface.
defaultType
This specifies whether the attribute must be specified in the instance, and if it is not, what the attribute value will be if not provided.
defaultValue
This provides an interface to a Node whose children make up the default value for an attribute. This value is used if the attribute was not given an explicit value in the document instance.
attributeList
The AttributeList object represents a collection of Attribute objects, indexed by attribute name. AttributeList objects are used to represent collections of Attribute objects which can be accessed by name. The Attribute objects contained in a AttributeList may alos be accessed by ordinal index. In most cases, AttributeList objects are created from Element objects.
getAttribute
Retrieve an Attribute instance from the list by its name. If it is not present, a null is returned.
setAttribute
Add a new attribute to the end of the list and associate it with the given name. If the name already exists, the previous Attribute object is replaced, and returned. If no object of the same name exists, null is returned, and the named Attribute is added to the end of the AttributeList object; that is, it is accessible via the item method using the index one less than the value returned by getLength.
Remove
Removes the Attribute instance named from the list and and returns it. If the name provided does not exist, the NoSuchAttributeException is thrown.
Item
Returns the (zero-based) indexed Attribute item in the collection. If index is greater than or equal to the number of nodes in the list, a NoSuchAttributeException is thrown.
GetLength
Returns the number of Attributes in the AttributeList instance.
The ICDATASection interface
CDATA sections are used in the document instance, and provide a region in which most of the XML delimiter recognition does not take place. The primary purpose is for including material such as XML fragments, without needing to escape all the delimiters. The data attribute of the Text node holds the text that was contained by the CDATA section. Note that this may contain characters that need to be escaped outside of CDATA sections.
The IComment interface
Represents the content of a comment, i.e. all the characters between the starting ''. Note that this is the definition of a comment in XML, and, in practice, HTML, although some HTML tools may implement the full SGML comment structure.
data
The content of the comment, exclusive of the comment begin and end sequence.
The IDOM interface
The "DOM" interface provides a number of methods for performing operations that are independent of any particular instance of the document object model. Although IDL does not provide a mechanism for expressing the concept, the methods supplied by the DOM interface will be implemented as "static", or instance independent, methods. This means that a client application using the DOM does not have to locate a specific instance of the DOM object; rather, the methods are will be available directly on the DOM class itself and so are directly accessible from any execution context.
CreateDocument
Creates a document of the specified type.
HasFeature
Returns TRUE if the current DOM implements a given feature, FALSE otherwise.
The IDocFragment interface
The IDocFragment object represents the root of a lightweight document or document fragment.
masterDoc
This provides access to the Document object associated with this DocumentFragment.
The IDocument interface
The IDocument object extends the DocFragment interface to represent the root node of a standalone document. The IDocument object represents the entire HTML or XML document. Conceptually, it is the root of the document tree, and provides the primary access to the document's data. Since IDocument inherits from DocumentFragment, its children are contents of the Document, e.g., the root Element, the XML prolog, any processing instructions and or comments, etc. Since Elements, Text nodes, Comments, PIs, etc. cannot exist outside a Document, the Document interface also anchors the "factory" methods that create these objects.
documentType
For XML, this provides access to the Document Type Definition ( see DocumentType ) associated with this XML document. For HTML documents and XML documents without a document type definition this returns the value null.
documentElement
This is a "convenience" attribute to jump directly to the child node that is the root element of the document.
contextInfo
CreateDocumentContext
Create and return a new DocumentContext.
CreateElement
Create an element based on the tagName. Note that the instance returned may implement an interface derived from Element. The attributes parameter can be null if no attributes are specified for the new Element.
CreateTextNode
Create a Text node given the specified string.
CreateComment
Create a Comment node given the specified string.
CreatePI
Create a PI node given the specified name and data strings.
CreateAttribute
Create an Attribute of the given name and specified value. Note that the Attribute instance can then be set on an Element using setAttribute method.
CreateAttributeList
Create an empty AttributeList.
GetElementsByTagName
Returns an iterator through all subordinate Elements with a given tag name.
The IDocumentContext interface
The IDocumentContext object is repository for meta-data about a document, such as source, creation date, and other creation context information. This object will be fully specified in the level two DOM specification.
document
The IDocumentType interface
Each document has a ( possibly null ) attribute that contains a reference to an IDocumentType object. The IDocumentType class provides an interface to access all of the entity declarations, notation declarations, and all the element type declarations. NOTE: There is no way currently of accessing the list of entities declared within a DTD. The W3C will add this once discussion about entity representation is completed.
name
The name attribute holds the name of the DTD, i.e. the name immediately following the DOCTYPE keyword.
externalSubset
This attribute's children reference the list of nodes ( definitions ) that occurred in the external subset of a document.
internalSubset
The internal subset's children constitute all the definitions that occurred within the internal subset of a document ( the part that appears within the document instance).
generalEntities
This is a Node whose children constitute the set of general entities that were defined within the external and the internal subset.
parameterEntities
This is a Node whose children constitute the set of parameter entities that were defined within the external and the internal subset. All objects supporting the INode interface that are accessed through this attribute will also support the IEntity interface.
notations
This is a Node whose children constitute the set of notations that were defined within the external and the internal subset. All objects supporting the INode interface that are accessed through this attribute will also support the Entity interface.
elementTypes
This is a Node whose children constitute the set of element types that were defined within the external and internal subset. All objects supporting the INode interface that are accessed through this attribute will also support the IElementDefinition interface.
The IElement interface
Element objects represent the elements in the HTML or XML document. Elements contain, as child nodes, all the content between the start tag, and the end tag of an element. Additionally, Element objects have a list of Attribute objects which represent the combination of those attributes explicitly specified in the document, and those defined in the document type definition which have default values. By far the vast majority ( apart from text ) of node types that authors will generally encounter when traversing a document will be Element nodes. These objects represent both the element itself, as well as any contained nodes.
GetTagName
This method returns the string that is the element's name.
attributes
The attributes for this element. The attributes will include the actual values of the element as well as any attributes defined in this element's document type definition with have default values.
SetAttribute
Adds a new attribute/value pair to an Element node object. If an attribute by that name is already present in the element, it's value is changed to be that of the Attribute instance.
Normalize
Puts all Text nodes sub-tree underneath this element into "DOM Normal Form", i.e., Text nodes are merged so that only markup ( e.g. tags and entity references ) separates Text nodes.
GetElementsByTagName
Returns an iterator through all subordinate Elements with a given tag name.
The IElementDefinition interface
The definition of each element defined within the external or internal subset ( providing it is parsed ), will be available through the elementTypes attribute of the DocumentType object. The name, attribute list, and content model are all available for inspection.
EMPTY
The element is an empty element, and cannot have content
ANY
The element may have character data, or any of the other elements defined within the DTD as content, in any order and sequence.
PCDATA
The element can have only PCDATA ( Parsed Character Data ) as content.
MODEL_GROUP
The element has a specific content model associated with it. The model is accessible through the contentModel attribute.
NAME
This is the name of the type of element being defined.
contentType
This attribute, one of the constant declarations in this interface, specifies the type of content of the element.
contentModel
If the contentType is MODEL_GROUP, then this will provide access to a ModelGroup object that is the root of the content model object heirarchy for this element. For other content types, this will be null.
attributeDefinitions
This children of this Node consist of the attributes that were defined to be on an ElementDefinition. Each object supporting the INode interface that is access through this attribute will also support the IAttributeDefinition interface.
inclusions
The children of this Node define a list of element type names that are included in the content model of this element by the SGML inclusion/exception mechanism ( not available from XML, but used in HTML ).
exceptions
This children of this node define a list of element type names that are excluded from the content model of this element by the SGML inclusion/exception mechanism ( not available from XML, but used in HTML ).
The IElementToken interface
Token for an element declaration.
OPT
The ? occurrence indicator.
PLUS
The + occurrence indicator.
REP
The * occurrence indicator.
name
The element type name.
occurrence
The number of times this element can occur.
The IEntityDeclaration interface
replacementString
The string that a reference to this entity is replaced with. It may contain markup and entity references. It does not apply to un-parsed entities.
replacementSubtree
The parsed subtree that references to this entity would logically point to. All markup in the replacement string is represented as sub-trees, and entity references are expanded.
The IEntityReference interface
EntityReference objects are inserted into the initial structure model by the XML processor. XML does not mandate that a non-validating XML processor read and process entity declarations make in the external subset or that are declared in external parameter entities. This means that parsed entities that are declared in the external subset need not be expanded by some classes of applications. XML contains the notion of "parsed entities" that are declared in the DTD, defined either internally in a document or in an external file, and referenced one or more places in the document. In any event, parsed entities allow an abstract reference to some arbitrarily large or complex piece of text and markup. Parsed entities are one type of general entity. The other type of general entity that XML defines is the unparsed entity, used for embedding data that is not in XML format in an XML document. It is commonly used for images. Parameter entities are used in DTDs for similar purposes as parsed entities in document instances; namely they allow an abstract reference to some part of the DTD. XML defines a number of rules about the allowed content of a parameter entity; the reader is referred to the XML specification for details.
IsExpanded
The default view of the entities is to be expanded.
Expand
The IModelGroup interface
The ModelGroup object represents the content model of an ElementDefinition. The content model is represented as a tree, where each node specifies how its children are connected, and the number of times that it can occur within its parent. Leaf nodes in the tree are either PCDATAToken or ElementToken.
OPT
The ? occurrence indicator.
PLUS
The + occurrence indicator.
REP
The * occurrence indicator.
OR
The | connection indicator.
SEQ
The , connection indicator.
AND
The ?? connection indicator.
occurrence
The number of times this model can occur.
connector
Describes how the tokens are connected together.
tokens
The children of this node define the list of tokens in this model group.
The INode interface
The Node object is the primary datatype for the entire Document Object Model. It represents a single node in the document tree. Nodes may have, but are not required to have, an arbitrary number of child nodes.
GetNodeType
Returns an indication of the underlying Node object's type. The actual type of the returned data is language binding dependent; the IDL specification uses an enum, and it is expected that most language bindings will represent this runtime-queryable Node type using an integral data type. The names of the node type enumeration literals are straightforwardly derived from the names of the actual Node subtypes, and are fully specified in the IDL definition of Node in the IDL definition in Appendix A of the W3C Document Object Model (Core) Level 1 document.
GetParentNode
Returns the parent of the given Node instance. If this node is the root of the document object tree, or if the node has not been added to a document tree, null is returned.
GetChildNodes
Returns a NodeIterator object that will enumerate all children of this node. If there are no children, an iterator that will return no nodes is returned. The content of the returned NodeIterator is "live" in the sense that changes to the children of the Node object that it was created from will be immediately reflected in the nodes returned by the iterator; it is not a static snapshot of the content of the Node. Similarly, changes made to the nodes returned by the iterator will be immediately reflected in the tree, including the set of children of the Node that the NodeIterator was created from.
HasChildNodes
Returns true if the node has any children, false if the node has no children at all. This method exists both for convenience as well as to allow implementations to be able to bypass object allocation, which may required for implementing getChildNodes.
GetFirstChild
Returns the first child of a node. If there is no such node, null is returned.
GetPreviousSibling
Returns the node immediately preceding the current node in a breadth-first traversal of the tree. If there is no such node, null is returned.
GetNextSibling
Returns the node immediately following the current node in a breadth-first traversal of the tree. If there is no such node, null is returned.
InsertBefore
Inserts a child node ( newChildbefore the existing child node refChild. If refChild is null, insert newChild at the end of the list of children. If refChild is not a child of the Node that insertBefore is being invoked on, a NotMyChildException is thrown.
ReplaceChild
Replaces the child node oldChild with newChild in the set of children of the given node, and returns the oldChild node. If oldChild was not already a child of the node that the replaceChild method is being invoked on, a NotMyChildException is thrown.
RemoveChild
Removes the child node indicated by oldChild from the list of children and returns it. If oldChild was not a child of the given node, a NotMyChildException is thrown.
The INodeIterator interface
The NodeIterator object is used for iterating over a set of nodes specified by a "filter". Iterators are described in detail in the book Design Patterns, pages 257-271, from which the following sections are quoted: Intent Provide a way to access elements of an aggregate object sequentially without exposing its underlying representation. Applicability Use the Iterator pattern to access an aggregate object's content without exposing its internal representation. to support multiple traversals of aggregate objects. to provide a uniform interface for traversing different aggregate structures (that is, to support polymorphic iteration). A NodeIterator is a very simple iterator class that can be used to provide a simple linear view of the document hierarchy.
GetLength
This method returns the number of items that will be iterated over if the iterator is started at the beginning, and toNext() is called repeatedly until the end of the sequence is encountered. Note: This may be an expensive operation. NOTE: This method will always return the correct number of items in a single threaded environment, but may return misleading results in a multi-threaded, multi-user situations.
GetCurrent
This method returns the Node over which the iterator currently rests. NOTE: This may be unsafe in uncontrolled multi-user or multi-threaded applications.
ToNext
This method alters the internal state of the iterator such that the node it references is the next in the sequence the iterator is presenting relative to the current position. Null is returned if it is not possible to iterate any further.
ToPrevious
This method alters the internal state of the iterator such that the node it references is the previous node in the sequence the iterator is presenting relative to the current position. Null will be returned when it is not possible to iterate any further.
ToFirst
This method alters the internal state of the iterator such that the node it references is the first node in the sequence the iterator is presenting relative to the current position. Null will be returned if there are no items to iterate over.
ToLast
This method alters the internal state of the iterator such that the node it references is the last node in the sequence the iterator is presenting relative to the current position. Null will be returned only when there are no items to iterate over.
ToNth
This method alters the internal state of the iterator such that the node it references is the Nth node in the sequence the iterator is presenting relative to the current position. If the value specified by Nth is greater than the number that would be returned from getLength() a NoSuchNodeException is thrown. NOTE: This may be a slow operation.
ToNode
This method alters the internal state of the iterator such that it references the destNode node as the current position. If the node does not exist in the iterator, a NoSuchNodeException is thrown. NOTE: This may be a slow operation.
The INotation interface
This object is used to represent the definition of a notation within a DTD.
name
This is the name of the notation.
IsPublic
If a public identifier was specified in the notation declaration, this will be true, and the publicIdentifier attribute will contain the string for the public identifier.
publicIdentifier
If a public identifier was specified in the notation declaration, this will hold the public identifier string, otherwise it will be null.
systemIdentifier
If a system identifier was specified in the notation declaration, this will hold the system identifier string, otherwise it will be null.
The IPCDATAToken Interface
Token type for the string #PCDATA
The IPI interface
A PI node is a "processing instruction". The content of the PI node is the entire content between the delimiters of the processing instruction
name
XML defines a name as the first token following the the markup that begins the processing instruction, and this attribute returns that name. Form HTML, the returned value is null.
data
The content of the processing instruction, from the character immediately after the .
The IStringList interface
A sequence of wstring types.
The IText interface
The Text object contains the non-markup content of an Element. If there is no markup inside an Element's content, the text will be contained in a single Text object that is the child of the Element. Any markup will parse into child elements that are siblings of the Text nodes on either side of it, and whose content will be represented as Text node children of the markup element.
data
This holds the actual content of the text node. Text nodes contain just plain text, without markup and without entities, both of which are represented as separate objects in the DOM.
Append
Append the string to the end of the character data in this Text node.
Insert
Insert the string at the specified character offset.
Delete
Remove the number of characters specified by count starting at the specified character offset.
Replace
Replace the number of characters specified by count starting at the specified character offset with the string specified in data.
Splice
Insert the specified Element in the tree as a sibling of the Text node. The result of this operation may be the creation of up to 2 new Text nodes: The character data specified by the offset and count will form one Text node that will become the child of the inserted element and the remainder of the character data ( after the offset and count ) will form another Text node become a sibling of the original Text node.
The ITreeIterator interface
A TreeIterator is a NodeIterator that has additional methods that are specific to tree navigation.
NumChildren
This method returns the number of children that lie below the current node. NOTE: This method will always return the correct number of items in a single threaded environment, but may return misleading results in multi-threaded, multi-user situations.
NumPreviousSiblings
This method returns the number of siblings that lie previous to the current node. NOTE: This method will always return the correct number of items in a single threaded environment, but may return misleading results in multi-threaded, multi-user situations.
NumNextSiblings
This method returns the number of siblings that lie after the current node. NOTE: This method will always return the correct number of items in a single threaded environment, but may return misleading results in multi-threaded, multi-user situations.
ToParent
Move the iterator to the parent of the current node, if there is a parent. This method will return a null when there is no parent for the current node.
ToPreviousSibling
Move the iterator to the previous sibling of the current node, if there is one. This method will return null if there is no previous sibling for the current node.
ToNextSibling
Move the iterator to the next sibling of the current node, if there is one. This method will return null when there is no next sibling for the current node.
ToFirstChild
Move the iterator to the first child of the current node, if there is one. This method will return null when there is no children for the current node.
ToLastChild
Move the iterator to the last child of the current node, if there is one. This method will return null when there are no children for the current node.
ToNthChild
This method alters the internal state of the iterator such that the node it references is the Nth child of the current node. NOTE: The current draft W3C spec has no parameters on this method. This is impossible. IMS has added a parameter, Nth, for the time being. It is also ambiguous as to whether the method should return null or throw an exception when the value provided is greater than the number that would be returned from numChildren.
The IXMLNode interface
The XML implementation of the Node interface adds some methods that are needed to manipulate specific features of XML documents.
GetParentXMLNode
Returns the parent of the given Node instance. If this node is the root of the document object tree, or if this node is not part of a document tree, null is returned. The expandEntities parameter should be true if the view of the tree with parsed entities expanded should be navigated, false if the view without parsed entities expanded should be navigated.
GetChildXMLNodes
Returns a NodeIterator object that will enumerate all children of this node. If there are no children, an iterator that will return no nodes is returned. The content of the returned NodeIterator is "live" in the sense that changes to the children of the Node object that it was created from will be immediately reflected in the nodes returned by the iterator; it is not a static snapshot of the content of the Node. Similarly, changes made to the nodes returned by the iterator will be immediately reflected in the tree, including the set of children of the Node that the NodeIterator was created from. The expandEntities parameter should be true if the view of the tree with parsed entities expanded should be navigated, false if the view without parsed entities expanded should be navigated.
HasChildXMLNodes
Returns true if the node has any children, false if hte node has no children at all. This method exists both for convenience as well as to allow implementations to be able to bypass object allocation, which may be required for implementing getChildNodes(). The expandEntities parameter should be true if the view of the tree with parsed entities expanded should be navigated, false if the view without parsed entities expanded should be navigated.
GetFirstXMLChild
Returns the first child of a node. If there is no such node, null is returned. The expandEntities parameter should be true if the view of the tree with parsed entities expanded should be navigated, false if the view without parsed entities expanded should be navigated.
GetPreviousXMLSibling
Returns the node immediately preceding the current node in a breadth-first traversal of the tree. If there is no such node, null is returned. The expandEntities parameter should be true if the view of the tree with parsed entities expanded should be navigated, false if the view without parsed entities expanded should be navigated.
GetNextXMLSibling
Returns the node immediately following the current node in a breadth-first traversal of the tree. If there is no such node, null is returned. The expandEntities parameter should be true if the view of the tree with parsed entities expanded should be navigated, false if the view without parsed entities expanded should be navigated.
GetEntityReference
When navigating XML trees with expandedEntities set to true, the DOM programmer will on occasion get Nodes returned that are part of the expansion of an entity rather than actual nodes in the tree. This method returns the entity reference that generated a particular node, or null if it was not part of an entity reference expansion.
GetEntityDeclaration
When navigating XML trees with expandedEntities set to true, the DOM programmer will on occasion get Nodes returned that are part of the expansion of an entity rather than actual nodes in the tree. This method returns the declaration for the entity reference that generated a particular node, or null if it was not part of an entity reference expansion.
CORBA IDL
#ifndef _DOCUMENT_IDL_
#define _DOCUMENT_IDL_
module Document
{
typedef sequence StringList;
exception NoSuchNodeException {};
exception NotMyChildException {};
// Enumerator class for a node list
interface INodeEnumerator
{
INode GetFirst();
INode GetNext();
INode GetPrevious();
INode GetLast();
INode GetCurrent();
// The rationale for their existence is that the enumerator may be used
// internally to a method, which may return some interesting value, and
// therefore cannot also indicate whether the start or end of enumeration
// was reached. Any of the traversal methods affects the state, and
// so are not suitable for usage as predicates (unless possible state
// manipulation is acceptable).
boolean AtStart();
boolean AtEnd();
};
// Define the type for a sequence of nodes
interface INodeList
{
INodeEnumerator getEnumerator();
INode Item(in unsigned long index)
raises(NoSuchNodeException);
// This may be expensive to compute
unsigned long GetLength();
};
// Define the type for a sequence of nodes
interface IEditableNodeList : INodeList
{
void Replace(in unsigned long index, in INode replacedNode)
raises (NoSuchNodeException);
void Insert(in unsigned long index, in INode newNode)
raises (NoSuchNodeException);
INode Remove(in unsigned long index)
raises (NoSuchNodeException);
};
interface IDocumentType : INode
{
attribute wstring name;
attribute INodeList externalSubset;
attribute INodeList internalSubset;
attribute INamedNodeList notations;
attribute INamedNodeList elementTypes;
};
enum OccurrenceType
{
OPT, // ?
PLUS, // +
REP // *
};
interface IElementDefinition : INode
{
enum ContentType
{
EMPTY,
ANY,
PCDATA,
MODEL_GROUP
};
attribute wstring name;
attribute ContentType contentType;
attribute IModelGroup contentModel;
attribute INamedNodeList attributeDefinitions;
attribute StringList inclusions;
attribute StringList exceptions;
};
interface IModelGroup : INode
{
enum ConnectionType
{
OR, // |
SEQ, // ,
AND
};
attribute ConnectionType connector;
attribute OccurrenceType occurrence;
attribute INodeList tokens;
};
interface IPCDATAToken : INode
{
// Token type for the string #PCDATA
};
interface IElementToken: INode
{
attribute wstring name;
attribute OccurrenceType occurrence;
};
interface IAttributeDefinition : INode
{
enum DeclaredValueType
{
CDATA,
ID,
IDREF,
IDREFS,
ENTITY,
ENTITIES,
NMTOKEN,
NMTOKENS,
NOTATION,
NAME_TOKEN_GROUP
};
enum DefaultValueType
{
VALUE, // The default value was an attribute value
// specification without #FIXED.
FIXED,
REQUIRED,
IMPLIED
};
attribute wstring name;
attribute StringList allowedTokens;
attribute DeclaredValueType declaredType;
attribute DefaultValueType defaultType;
attribute INodeList defaultValue;
};
interface INotation : INode
{
attribute wstring name;
attribute boolean isPublic;
attribute wstring publicIdentifier;
attribute wstring systemIdentifier;
};
typedef sequence buffer;
interface IEntity : INode
{
attribute wstring name;
attribute boolean isParameterEntity;
};
interface IInternalEntity : IEntity
{
attribute wstring content;
};
interface IExternalEntity : IEntity
{
attribute boolean isNDATA;
attribute boolean isPublic;
attribute string publicIdentifier;
attribute string systemIdentifier;
};
interface IExternalTextEntity : IExternalEntity
{
attribute wstring content;
};
interface IExternalNDATAEntity : IExternalEntity
{
attribute Notation notation;
attribute buffer content;
};
interface INDATA : INode
{
attribute buffer content;
};
interface IDOM
{
IDocument CreateDocument(in wstring type);
boolean HasFeature(in wstring feature);
};
interface IDocumentContext
{
attribute IDocument document;
};
interface IDocumentFragment : INode
{
attribute IDocument masterDoc;
};
interface IDocument : IDocumentFragment
{
attribute INode documentType;
attribute IElement documentElement;
attribute IDocumentContextcontextInfo;
IDocumentContext CreateDocumentContext();
IElement CreateElement( in wstring tagName,
in IAttributeList attributes);
IText CreateTextNode(in wstring data);
IComment CreateComment(in wstring data);
IPI CreatePI(in wstring name,
in wstring data);
IAttribute CreateAttribute(in wstring name,
in INode value);
IAttributeList CreateAttributeList();
ITreeIterator CreateTreeIterator(in INode node);
INodeIterator GetElementsByTagName(in wstring tagname);
};
interface INode
{
// NodeType
const int DOCUMENT = 1;
const int ELEMENT = 2;
const int ATTRIBUTE = 3;
const int PI = 4;
const int COMMENT = 5;
const int TEXT = 6;
int GetNodeType();
INode GetParentNode();
INodeIterator GetChildNodes();
boolean HasChildNodes();
INode GetFirstChild();
INode GetPreviousSibling();
INode GetNextSibling();
INode InsertBefore(in INode newChild,
in INode refChild );
INode ReplaceChild(in INode newChild,
in INode oldChild)
raises (NotMyChildException);
INode RemoveChild(in INode oldChild)
raises(NotMyChildException);
};
exception NotMyChildException {};
interface INodeIterator
{
unsigned long GetLength();
unsigned long GetCurrentPos();
boolean AtFirst();
boolean AtLast();
INode ToNextNode();
INode ToPrevNode();
INode ToFirstNode();
INode ToLastNode();
INode MoveTo(in int n);
};
interface ITreeIterator : INodeIterator
{
unsigned long NumChildren();
unsigned long NumPreviousSiblings();
unsigned long NumNextSiblings();
INode ToParent();
INode ToPreviousSibling();
INode ToNextSibling();
INode ToFirstChild();
INode ToLastChild();
INode ToNthChild(in int n)
raises( NoSuchNodeException );
};
interface IAttribute
{
wstring GetName();
wstring GetValue();
attribute boolean specified;
wstring ToString();
};
interface IAttributeList
{
IAttribute GetAttribute(in wstring attrName);
IAttribute SetAttribute(in Attribute attr);
IAttribute Remove(in wstring attrName)
raises( NoSuchAttributeException );
IAttribute Item(in unsigned long index)
raises( NoSuchAttributeException );
unsigned long GetLength();
};
interface IElement : INode
{
wstring GetTagName();
INodeIterator GetAttributes();
wstring GetAttribute(in name name);
void SetAttribute(in string name,
in string value);
void RemoveAttribute(in wstring name);
IAttribute GetAttributeNode(in name name);
void SetAttributeNode(in IAttribute newAttr);
void RemoveAttributeNode(in IAttribute oldAttr);
void GetElementsByTagName(in wstring tagname);
void Normalize();
};
interface IText : INode
{
attribute wstring data;
void Append(in wstring data);
void Insert(in int offset,
in wstring data);
void Delete(in int offset,
in int count);
void Replace(in int offset,
in int count,
in wstring data);
void Splice(in Element element,
in int offset,
in int count);
};
interface IComment : INode
{
attribute wstring data;
};
interface IPI : INode
{
attribute wstring name;
attribute wstring data;
};
interface IXMLNode
{
INode GetParentXMLNode(in boolean expandEntities);
INodeIterator GetChildXMLNodes(in boolean expandEntities);
boolean HasChildXMLNodes(in boolean expandEntities);
INode GetFirstXMLChild(in boolean expandEntities);
INode GetPreviousXMLSibling(in boolean expandEntities);
INode GetNextXMLSibling(in boolean expandEntities);
IEntityReference GetEntityReference();
IEntityDeclaration GetEntityDeclaration();
};
interface IDocumentType
{
attribute wstring name;
attribute INode externalSubset;
attribute INode internalSubset;
attribute INode generalEntities;
attribute INode parameterEntities;
attribute INode notations;
attribute INode elementTypes;
};
interface IElementDefinition : INode
{
// ContentType
const int EMPTY = 1;
const int ANY = 2;
const int PCDATA = 3;
const int MODEL_GROUP = 4;
attribute wstring name;
attribute int contentType;
attribute IModelGroup contentModel;
attribute INode attributeDefinitions;
attribute INode inclusions;
attribute INode exceptions;
};
interface IPCDATAToken : INode
{
};
interface IElementToken : INode
{
// OccurrenceType
const int OPT = 1;
const int PLUS = 2;
const int REP = 3;
attribute wstring name;
attribute int occurrence;
};
interface IModelGroup : INode
{
// OccurrenceType
const int OPT = 1;
const int PLUS = 2;
const int REP = 3;
// ConnectionType
const int OR = 1;
const int SEQ = 2;
const int AND = 3;
attribute int occurrence;
attribute int connector;
attribute INode tokens;
};
interface IAttributeDefinition : INode
{
// DeclaredValueType
const int CDATA = 1;
const int ID = 2;
const int IDREF = 3;
const int IDREFS = 4;
const int ENTITY = 5;
const int ENTITIES = 6;
const int NMTOKEN = 7;
const int NMTOKENS = 8;
const int NOTATION = 9;
const int NAME_TOKEN_GROUP = 10;
// DefaultValueType
const int FIXED = 1;
const int REQUIRED = 2;
const int IMPLIED = 3;
attribute wstring name;
attribute StringList allowedTokens;
attribute int declaredType;
attribute int defaultType;
attribute INode defaultValue;
};
interface INotation : INode
{
attribute wstring name;
attribute boolean isPublic;
attribute string publicIdentifier;
attribute string systemIdentifier;
};
interface IEntityDeclaration
{
attribute wstring replacementString;
attribute IDocumentFragment replacementSubtree;
};
interface IEntityReference
{
attribute boolean IsExpanded;
void Expand(in );
};
interface ICDATASection : IText
{
};
};
#endif // _DOCUMENT_IDL_
#ifndef _HTMLDOCUMENT_IDL_
#define _HTMLDOCUMENT_IDL_
#include "Document.idl"
module HTMLDocument
{
interface IHTMLStyle
{
// Hook for level two
};
interface IHTMLCollection : INodeList
{
INode namedItem(in wstring name);
// Same interface, different semantics
};
interface IHTMLDocument : IDocument
{
// These are all methods, because they do some processing
// of the document
IHTMLCollection GetImages();
IHTMLCollection GetApplets();
IHTMLCollection GetLinks();
IHTMLCollection GetForms();
IHTMLCollection GetAnchors();
IHTMLCollection GetScripts();
// These are methods because we have not defined a list
// of cookies anywhere in the model
wstring GetCookie();
wstring SetCookie(in wstring cookie);
readonly attribute wstring referrer;
readonly attribute wstring fileSize;
readonly attribute wstring fileCreatedDate;
readonly attribute wstring fileModifiedDate;
readonly attribute wstring fileUpdatedDate;
readonly attribute IHTMLLocation location;
attribute IHTMLElement body;
};
interface IHTMLLocation
{
attribute wstring href;
attribute wstring protocol;
attribute wstring host;
attribute wstring hostname;
attribute wstring port;
attribute wstring pathname;
attribute wstring query;
attribute wstring fragment;
void Reload(in boolean flag);
void Replace(in wstring url);
};
interface IHTMLElement : IElement
{
attribute wstring tagName;
attribute wstring className;
attribute wstring id;
attribute IHTMLStyle style;
attribute IHTMLElement parentElement;
attribute wstring title;
attribute wstring lang;
attribute wstring dir;
attribute wstring onClick;
attribute wstring onDblClick;
attribute wstring onKeyDown;
attribute wstring onKeyUp;
attribute wstring onKeypress;
attribute wstring onMouseOut;
attribute wstring onMouseOver;
attribute wstring onMouseMove;
attribute wstring onMouseUp;
attribute wstring onMouseDown;
attribute IHTMLCollection all;
readonly attribute IHTMLDocument document;
boolean Contains(in IHTMLElement pChild);
// Note the use of Object here!!!!
void AddAttribute(in wstring name, in IObject value, in long lFlags);
IObject GetAttribute(in wstring name,in long lFlags);
boolean RemoveAttribute(in wstring name, in long lFlags);
};
interface IHTMLLinkElement : IHTMLElement
{
attribute wstring href;
attribute wstring rel;
attribute wstring rev;
attribute wstring type;
attribute wstring media;
wstring GetReadyState();
};
interface IHTMLTitleElement : IHTMLElement
{
attribute wstring text;
};
interface IHTMLMetaElement : IHTMLElement
{
attribute wstring httpEquiv;
attribute wstring content;
attribute wstring name;
attribute wstring text;
attribute wstring url;
attribute wstring charset;
};
interface IHTMLBaseElement : IHTMLElement
{
attribute wstring href;
attribute wstring target;
};
interface IHTMLIsIndexElement : IHTMLElement
{
attribute wstring prompt;
attribute wstring action;
};
interface IHTMLStyleElement : IHTMLElement
{
attribute wstring type;
attribute boolean disabled;
attribute wstring media;
};
interface IHTMLBodyElement : IHTMLElement
{
attribute wstring background;
attribute wstring bgColor;
attribute wstring text;
attribute wstring link;
attribute wstring vlink;
attribute wstring alink;
};
interface IHTMLFormElement : IHTMLElement
{
attribute wstring action;
attribute wstring method;
attribute wstring target;
attribute wstring name;
attribute long length;
attribute IHTMLFormElement elements;
// Note the use of Object here!!!!
IHTMLElement GetItem(in IObject name, in IObject index);
IHTMLCollection GetTags(in wstring name);
};
interface IHTMLSelectElement : IHTMLElement
{
attribute long selectedIndex;
attribute long size;
attribute boolean multiple;
attribute wstring name;
attribute wstring type;
attribute wstring value;
attribute boolean disabled;
attribute long length;
readonly attribute IHTMLFormElement form;
attribute IHTMLCollection options;
void Add(in IHTMLElement element, in IHTMLElement before);
void Remove(in long index);
IHTMLElement GetItem(in wstring name);
IHTMLCollection GetTags(in wstring tagname);
};
interface IHTMLOptionElement : IHTMLElement
{
attribute wstring text;
attribute long index;
attribute boolean selected;
attribute wstring value;
attribute boolean defaultSelected;
readonly attribute IHTMLFormElement form;
};
interface IHTMLFieldSetElement : IHTMLElement
{
attribute wstring align;
};
interface IHTMLLegendElement : IHTMLElement
{
attribute wstring align;
};
interface IHTMLInputTextElement : IHTMLElement
{
attribute wstring value;
attribute wstring name;
attribute boolean disabled;
attribute wstring defaultValue;
attribute long size;
attribute long maxLength;
attribute boolean readOnly;
attribute boolean checked;
attribute boolean defaultChecked;
readonly attribute IHTMLFormElement form;
};
interface IHTMLTextAreaElement : IHTMLElement
{
attribute wstring type;
attribute wstring value;
attribute wstring name;
attribute boolean disabled;
attribute wstring defaultValue;
attribute boolean readOnly;
attribute long rows;
attribute long cols;
attribute wstring wrap;
readonly attribute IHTMLFormElement form;
};
interface IHTMLButtonElement : IHTMLElement
{
attribute wstring type;
attribute wstring value;
attribute wstring name;
attribute boolean disabled;
readonly attribute IHTMLFormElement form;
};
interface IHTMLLabelElement : IHTMLElement
{
attribute wstring htmlFor;
attribute wstring accessKey;
};
interface IHTMLAnchorElement : IHTMLElement
{
attribute wstring target;
attribute wstring href;
attribute wstring rel;
attribute wstring rev;
attribute wstring name;
attribute wstring accessKey;
attribute long tabIndex;
attribute wstring charset;
};
interface IHTMLBaseFontElement : IHTMLElement
{
attribute wstring color;
attribute wstring face;
attribute long size;
};
interface IHTMLBRElement : IHTMLElement
{
attribute wstring clear;
};
interface IHTMLImgElement : IHTMLElement
{
attribute boolean isMap;
attribute wstring useMap;
attribute wstring border;
attribute long vspace;
attribute long hspace;
attribute wstring alt;
attribute wstring src;
attribute wstring lowSrc;
attribute wstring align;
attribute long width;
attribute long height;
};
interface IHTMLFontElement : IHTMLElement
{
attribute wstring color;
attribute wstring face;
attribute long size;
};
interface IHTMLModElement : IHTMLElement
{
attribute wstring cite;
attribute wstring dateTime;
};
interface IHTMLObjectElement : IHTMLElement
{
// Note the use of Object here!!!!
attribute IObject object;
attribute wstring classId;
attribute wstring data;
attribute wstring align;
attribute wstring name;
attribute wstring codeBase;
attribute wstring codeType;
attribute wstring code;
attribute wstring type;
attribute long width;
attribute long height;
attribute wstring altHtml;
attribute long vspace;
attribute long hspace;
attribute long tabIndex;
readonly attribute IHTMLFormElement form;
};
interface IHTMLQuoteElement : IHTMLElement
{
attribute wstring cite;
};
interface IHTMLScriptElement : IHTMLElement
{
attribute wstring src;
attribute wstring text;
attribute wstring type;
attribute wstring language;
};
interface IHTMLUListElement : IHTMLElement
{
attribute boolean compact;
attribute wstring type;
};
interface IHTMLOListElement : IHTMLElement
{
attribute boolean compact;
attribute wstring type;
attribute long start;
};
interface IHTMLLIElement : IHTMLElement
{
attribute wstring type;
attribute long value;
};
interface IHTMLDListElement : IHTMLElement
{
attribute boolean compact;
};
interface IHTMLDivElement : IHTMLElement
{
attribute wstring align;
};
interface IHTMLHRElement : IHTMLElement
{
attribute wstring align;
attribute boolean noShade;
attribute long width;
attribute long size;
};
interface IHTMLParaElement : IHTMLElement
{
attribute wstring align;
};
interface IHTMLHeaderElement : IHTMLElement
{
attribute wstring align;
};
interface IHTMLMapElement : IHTMLElement
{
IHTMLCollection GetAreas();
attribute wstring name;
};
interface IHTMLAreaElement : IHTMLElement
{
attribute wstring shape;
attribute wstring coords;
attribute wstring href;
attribute wstring target;
attribute wstring alt;
attribute boolean noHref;
attribute long tabIndex;
};
interface IHTMLTableCaption : IHTMLElement
{
attribute wstring align;
};
interface IHTMLTable : IHTMLElement
{
attribute long cols;
attribute wstring border;
attribute wstring frame;
attribute wstring rules;
attribute long cellSpacing;
attribute long cellPadding;
attribute wstring bgColor;
attribute wstring align;
attribute long width;
attribute IHTMLTableCaption caption;
attribute IHTMLTableSection head;
attribute IHTMLTableSection tfoot;
IHTMLCollection GetRows();
IHTMLCollection GetBodies();
IHTMLElement CreateTHead();
void DeleteTHead();
IHTMLElement CreateTFoot();
void DeleteTFoot();
IHTMLTableCaption CreateCaption();
void DeleteCaption();
IHTMLElement InsertRow(in long index);
void DeleteRow(in long index);
};
interface IHTMLTableCol : IHTMLElement
{
attribute long span;
attribute wstring align;
attribute wstring valign;
attribute long width;
};
interface IHTMLTableSection : IHTMLElement
{
IHTMLCollection GetRows();
IHTMLElement InsertRow(in long index);
void DeleteRow(in long index);
attribute wstring align;
attribute wstring valign;
};
interface IHTMLTableRow : IHTMLElement
{
attribute long rowIndex;
attribute long sectionRowIndex;
attribute wstring align;
attribute wstring valign;
attribute wstring bgColor;
IHTMLCollection GetCells();
IHTMLElement InsertCell(in long index);
void DeleteCell(in long index);
};
interface IHTMLTableCell : IHTMLElement
{
attribute long cellIndex;
attribute long rowSpan;
attribute long colSpan;
attribute wstring align;
attribute wstring valign;
attribute wstring bgColor;
attribute boolean noWrap;
attribute long width;
attribute long height;
};
interface IHTMLCommentElement : IHTMLElement
{
attribute wstring text;
};
interface IHTMLFrameSetElement : IHTMLElement
{
attribute wstring rows;
attribute wstring cols;
};
interface IHTMLFrameElement : IHTMLElement
{
attribute wstring src;
attribute wstring name;
attribute boolean noResize;
attribute wstring scrolling;
attribute wstring frameBorder;
attribute long marginWidth;
attribute long marginHeight;
};
interface IHTMLIFrameElement : IHTMLElement
{
attribute wstring src;
attribute wstring name;
attribute wstring scrolling;
attribute wstring align;
attribute long marginWidth;
attribute long marginHeight;
attribute long width;
attribute long height;
};
};
#endif // _HTMLDOCUMENT_IDL_
DCOM IDL
Security Service Interfaces
Origin of Interfaces
The following information is based entirely on National Institute of Standards and Technologys Role Based Access Control model. The only changes that have been made, other than the addition of IMS context information, is the harmonization of interface signatures with the rest of the IMS and the possible removal of some low level NIST dependencies.
Interface Descriptions
Module RBAC
The IActiveRoleSet interface
This is a subset of the authorized role set. Beyond RBAC 0, principles of mutual exclusion are introduced. Roles in the authorized role set may be mutually exclusive with other roles in that set. The active role set is a subset that contains no mutually exclusive roles.
The IAssignedRoleSet interface
This is the set of roles directly assigned to the user. This is the role set that the role administrator edits to grant/revoke priviledges.
The IAuthorizedRoleSet interface
This is the set of roles associated with the subject. This is a superset of the assigned role set. This set includes any roles inherited by roles belonging to the assigned role set. For RBAC 0 the authorized role set is the same as the assigned role set.
The IInherit interface
This type maps a role to the set of roles from which it inherits.
role
inheritedRoles
The IOperation interface
operationID
The identifier of an operation which will apply to the objects in targets.
targets
The target objects that an operation applies to.
The IOperationDB interface
This is the operations database
The IRBAC0 interface
RBAC 0 is the most basic type of role based access control service. It defines the functionality to define users and roles without the use of inheritance or separation of duty. These basic services are built on by the other classes of RBAC service.
ActiveRoles
Retrieve the active role set (ARS) for the subject.
AddRole
Add a role to the role and explanatory text to the database. If the database already has that role defined then return the database unchanged.
AddUser
Add a role to the user and explanatory text to the database. If the database already has that user defined then return the database unchanged.
AssignRole
Assign a role to a particular user.
AuthUserCount
Return the number of users currently authorized to a role.
Cardinality
Return the cardinality of a role. Role cardinality is the maximum number of users that can be authorized to a role.
DeassignRole
Remove a role assignment from a user.
GetRole
Retrieve a role from the role database. It is assumed that the existence of the role has already been checked.
GetUser
Retrieve a user from the user database. It is assumed that the existence of the user has already been checked
ExistsRole
Verify that a given role id exists in the role database. The method returns true if the role exists. NOTE: The first parameter of this method may be changed from type String to type Role.
ExistsUser
Verify that a given user id exists in the user database. The method returns true if the user exists. NOTE: The first parameter of this method may be changed from type String to type User.
HasARS
Detect whether the subject currenty has an active role set (ARS) defined.
HasAssignedRole
Test whether a user has a particular role. This call assumes that the existence of the user has already been verified.
HasAnyAssignedRoles
Test whether a user is assigned any roles. If the user exists in the user database, then check that the userRoles attribute of the User is not empty.
HasAuthorizedRole
public abstract Boolean hasAuthorizedRole(String roleID)
Test whether a subject is authorized to a particular role.
MutuallyExclusiveActivation
Return the set of roles that are mutually exclusive of the given role for purposes of activating roles.
OperationObjects
Retrieve the objects on which a particular operation is permitted.
RmRole
Remove a role from the role database.
RmUser
Remove a user from the user database.
RoleAssigned
Test whether a role is currently assigned to any users.
RoleMembers
Retrieve the users that are associated with a particular role.
RoleOperations
Retrieve the operations permitted by a particular role.
SetCardinality
Set the cardinality of a role to n. The parameter is an integer so that the value can be set to -1 to signal that cardinality restrictions do not apply.
SetPermittedOperation
Assign an operation to a particular role.
SubjectUser
Return the user associated with the given subject.
UserAuthorizedRoles
This is the set of authorized roles for a given user. In RBAC 0, this is the same as the assigned roles for a user since role inheritance and role separation is not available.
UserAssignedRoles
Retrieve the roles assigned to a particular user.
UserHasAssignedRole
Test whether the user has a particular role assigned.
VerifyRBACaccess
Verify that the subject can perform a given operation. Remember that a particular operation includes the target object being acted upon.
MutuallyExclusiveAuthorization
Return the set of roles that are mutually exclusive of the given role for purposes of authorizing roles
The IRBAC1 interface
RBAC 1 takes RBAC 0 and adds the notion of inheritance relationships between roles
AuthorizedRoles
Returns all of the roles authorized to a subject. ( More precisely to a subject's assigned role set and its inheritance database. )
EstablishInheritance
Establish that role 1 inherits from role 2.
HasAuthorizedRole
Tests whether a given role is an authorized role given the assigned role set and the inheritance database inherit.
Inherits
Tests whether a role inherits from another role with up to three intermediate objects in between.
InheritsDirect
Tests whether a role inherits directly from another role.
RemoveInheritance
Remove role 2 as a role inherited by role 1. If the inheritance relationship does not exist, removing it will have no effect on the system.
The IRBAC2 interface
RBAC 2 takes RBAC 0 and adds the notion of separation of duty. Separation of duty establishes mutual exclusion between roles on two levels. Static separation of duty controls how roles are assigned to users. A user cannot be assigned two roles which are labeled statically separate. Dynamic separation of duty controls how the active role set is formed for the user. Two roles with dynamic separation cannot both end up in the active role set.
AssignRole
Static separation of duty affects the operation of assignRole. Therefore it is overloaded here to provide to necessary functionality. In attempting to assign role 1, the entire contents of the assigned role set is checked for a role which is statically separate from role 1. If the assignment is successful, the new assigned role set is returned.
EstablishStaticSeparation
Establish a static separation of duty between two roles. The fourth argument is the dynamic separation database. This is because only a single separation of duty relationship between two roles is allowed.
RemoveStaticSeparation
Remove a static separation of duty between two roles.
RemoveDynamicSeparation
Remove a dynamic separation of duty between two roles.
The IRBAC3 interface
RBAC 3 takes RBAC 0 and includes both inheritance and separation of duty.
AssignRole
This override of assignRole converges the features from RBAC 1 and RBAC2. If the assignment is successful, the new assigned role set is returned.
EstablishInheritance
This override of establishInheritance allows for the checking of any separation of duty conflicts.
EstablishStaticSeparation
This override of RBAC 2 incorporates inheritance into the method.
EstablishDynamicSeparation
This override of RBAC 2 incorporates inheritance into the method.
The IRole interface
The basic definition of a role is a structure maintaining cardinality information about the role: the membership limit and current number of users assigned the role. The isFull flag allows easy modeling of delete functions. Negative values for membershipLimit indicate that no membership limit has been imposed.
roleID
IsFull
MembershipLimit
The IRoleDB interface
This is the collection of all roles defined in the security system.
The IRoleUserDB interface
This is the mapping of users to the roles that they are assigned
The ISecurity interface
authorizedRoles
digitalCertificate
InvokeSecure
The ISeparationOfDuty interface
This type maps a role to the set of roles that conflict with it. It is defined generally so as to apply to both static and dynamic separation.
role
roleSet
The ISubject interface
This is the label given to a user session.
userID
activeRoleSet
The active role set is a subset of the authorized role set. Its contents are restricted by dynamic separation of duty relationships between roles.
authorizedRoleSet
The set of roles associated with the subject. This includes all roles inherited by the roles in the assigned role set.
The IUser interface
This is the security system's definition of a user. It contains the user identifier and the roles that the user is assigned, along with a flag indicating if the user is able to take on more roles.
userID
IsFull
UserRoles
The set of roles directly assigned to the user. This is the role set that the role administrator edits to grant/revoke priviledges.
CORBA IDL
DCOM IDL
Commerce Service Interfaces
Interface Descriptions
Module IMSCommerce
The IMeter Interface
Login
This method attaches a meterable product to the commerce environment and identifiers the microaccount to be charged for subsequent transacdtions.
Logout
The method marks the completion of a products usage of a microaccount. No further usages are
allowed until a Login starts a new commerce session.
Query
The Query method reports whether this product will be allowed another usage. The method is able to utilize information stored in the cache during the prior cache upload session. The method returns true if another usage is allowed, false if not. If metering logic is not installed on the system, false should be returned. If the account is out of balance, false should be returned.
Commit
The Commit method finalizes a usage of the product in the cache.
Flush
The Flush method empties all information in the cache to the back office and downloads a fresh reading of the enclosing Login account status. This method is for the ( hopefully ) rare products that cannot rely on the normal cache flush logic, which uploads the cache automatically when the cache fills or monthy. In addition, this may be used by high value products whose value is sufficiently high that an immediate redetermination of the users micro-account status must be obtained before accepting another transaction.
The IBackOffice interface
UploadCache
This method is called by the IMeter::Flush method to flush the meters cache to the back office. A StatusTable is an encrypted key/value table containing the account status of all customer login records in this batch of cache. The keys are customer ids and the values are booleans. The cache will decrypt this with the back offices public key and store it internally to provide the values for all subsequent Query calls for the corresponding customer id.
The MeterReadings string contains all of the meter readings from this meters cache, encrypted for transmission with the meter ids public key. This string decrypts into an array of code/value pairs:
CodeMeaningValue1LoginCustomer id2LogoutCustomer id3QueryProduct id4CommitProduct idDownloadBalance
This method internally calls UploadCache and returns a FinancialAmount, the current balance in the CIDs microaccount.
CORBA IDL
DCOM IDL
Appendix B: The Role of RMI
This document lays out the API specifications for IMS systems at a core level. The IDL descriptions of objects and method calls at this level are meant to be sufficient for developing IMS systems based on CORBA or DCOM distributed object technologies. A subset of these objects and methods which are particularly useful to developers of runtime applications who need to communicate with an IMS system to get information on resources, users and groups will be made available through RMI interfaces. This will increase the availability of useful core services across different browser platforms that may not be able to support communication with either of the underlying CORBA or DCOM object technologies.
Many application level programmers may still find the IMS core interfaces intimidating with or without RMI interfaces. To meet the needs of these programmers we will be developing a set of higher application level APIs which use RMI indirectly but shield the user from the complexities of server lookup and binding protocols. These object facades will organize and recast the underlying RMI server calls in ways that make sense to content developers and users, exposing the most convenient calls and providing additional services. An example of such a user convenient faade is the Resource Agent described in the Proof of Concept Section of this document. The Resource Agent is a Java class that exposes the most useful methods and data of the prototype's Message Channel Manager and Coordinator. When it is instantiated it makes an RMI connection to both the Message Channel Manager and the System Coordinator object from which it gathers information that is useful to the application at run time. The application is unaware that RMI has been invoked and is running in the background.
The Proof of Concept Implementation has made use of RMI to:
provide convenient access to the IMS Message Channel
provide convenient access to the IMS Coordinator object to get information
on users, groups and resources
implement convenient faade objects for application level programming
The question arises, to what extent will RMI continue to be supported in the evolution of the Specifications and reference implementation? The answer is that:
The prototype API in general will be enhanced to harmonize with the developing Specifications and public comment.
The revised Specifications will contain official RMI bindings.
The straightforward RMI bindings to the MessageChannel will remain much the same, with extensions to support a Notification layer and the more elaborate form of Message objects.
The RMI bindings to the IMS Coordinator will be deprecated in subsequent releases of the prototype. Services provided by the Coordinator will now be performed by calls to methods on the Resource object itself.
The faade objects such as the Messenger and Resource Agent will almost certainly come under close scrutiny and be redesigned to reflect changing design, best practices and user critiques. Developers should not rely on continued support for the method APIs in these faade objects, however convenient. They should use RMI calls directly which are less subject to change.
In summary application developers may feel reasonably confident in using the APIs described in the Channel Manager RMI Interface section of this document but should use the Messenger, Message, and Resource Agent objects guardedly in anticipation of possible deprecations as the prototype is revised in accordance with the evolving specifications.
Interface Descriptions
CORBA IDL
DCOM IDL
EDUCOM/NLII Instructional Management Systems Project PAGE 4
Copyright 1998 Educom Draft 0.5 April 29, 1998
Mgmt. System from Company XYZ
Mgmt. System from Company ABC
Content
Service Organizations
logo
figure
Internet
Learner Data
Tools
Content
People
document
. E F H i k l z { & ' A B C D E \ ] w x y z { ͼͲ͔ͨ͊͞ jq UmH j UmH jw UmH j UmH j} UmH j UmH
j UmH mH
5;CJ j 5;CJ UCJ 5CJ 5CJ OJ QJ 5CJ OJ QJ 5CJ$ OJ QJ 6 . F G H T i j k F | 1 h ] [ |
!
!
!
. F G H T i j k F | 1 h ] [ |
\
Q 9 v
O ~ Y P N S G z ' l = n 8 H ~ Y 7 b , - . / 0 H I c d e f g
< = W X Y [ \ : j UmH jY UmH j UmH j_ UmH j UmH je UmH j UmH jk UmH mH
j UmH j UmH =: ; U V W Y Z [ \ v w x z {
;
<
V
W
X
Z
[
0 1 K L M O j; UmH j
UmH jA
UmH j UmH jG UmH j UmH jM UmH j UmH jS UmH mH
j UmH =|
\
Q 9 v
O ~ Y P
!
!
O P 3 4 5 7 8 U V p q r t u
b
c
}
~
j UmH j# UmH j UmH j) UmH j
UmH j/
UmH j UmH j5 UmH j UmH mH
j UmH =
. / I J K M N n o ] ^ x y z | }
8 9 S j UmH j UmH j UmH j UmH j UmH j UmH j UmH j UmH mH
j UmH >S T U W X i j / 0 J K L N O _ ` z { | ~ j UmH jp UmH j UmH jv UmH j UmH j| UmH j UmH j UmH mH
j UmH j UmH =P N S G z ' l = n
!
!
!
- . H I J L M ^ _ y z { } ~ 2 3 M N O Q R b c } ~ jR UmH j UmH jX UmH j UmH j^ UmH j UmH jd UmH j UmH jj UmH mH
j UmH = & ' A B C E F Y Z t u v x y ! " # % & K L f g h j k j UmH j: UmH j UmH j@ UmH j UmH jF UmH j UmH jL UmH j UmH mH
j UmH =
7 8 9 ; < M N h i j l m | } 2 3 4 6 7 _ ` z j$ UmH j"$ UmH j# UmH j(# UmH j" UmH j." UmH j! UmH j4! UmH mH
j UmH > 8 H ~ Y 7 | R 0 g
!
!
z { | ~
' ( B C D F G ] ^ x y z | } 8 j) UmH j( UmH j
( UmH j' UmH j' UmH j&