OSS Design Patterns A Pattern Approach To The Design of Telecommunications Managemen WWW - Update-Boo

OSS Design Patterns
A Pattern Approach to the Design of

Telecommunications Management Systems
Colin Ashford and Pierre Gauthier
OSS Design Patterns

A Pattern Approach to the Design of
Telecommunications Management Systems
ABC
Colin Ashford
OSS Evolution
www.ossevolution.com
E-mail: ashford@ossevolution.com
Pierre Gauthier
OSS Wave
www.osswave.com
E-mail: pierre.gauthier@osswave.com
ISBN 978-3-642-01395-9 e-ISBN 978-3-642-01396-6
DOI 10.1007/978-3-642-01396-6
Library of Congress Control Number: Applied for

c 2009 Springer-Verlag Berlin Heidelberg
This work is subject to copyright. All rights are reserved, whether the whole or part of the mate-
rial is concerned, specifically the rights of translation, reprinting, reuse of illustrations, recitation,
broadcasting, reproduction on microfilm or in any other way, and storage in data banks. Dupli-
cation of this publication or parts thereof is permitted only under the provisions of the German
Copyright Law of September 9, 1965, in its current version, and permission for use must always
be obtained from Springer. Violations are liable to prosecution under the German Copyright Law.
The use of general descriptive names, registered names, trademarks, etc. in this publication does
not imply, even in the absence of a specific statement, that such names are exempt from the relevant
protective laws and regulations and therefore free for general use.
Typesetting: Data supplied by the authors
Production: Scientific Publishing Services Pvt. Ltd., Chennai, India
Cover Design: eStudio Calamar, Steinen-Broo
Printed in acid-free paper
987654321
springer.com
In loving memory of Carole and for Jean-Loup
—Pierre
For Jo and Leon-Philip
—Colin
Foreword
The management of telecommunications networks and services is one of the most

challenging of software endeavors—partly because of the size and the distributed
nature of networks; partly because of the convergence of communications technolo-
gies; but mainly because of sheer complexity and diversity of networks and services.
The TM Forum s Solutions Frameworks (NGOSS) help address these challenges
by providing a framework for the development of management applications—those
software applications that provide the building blocks for management solutions.
The members of the TM Forum have elaborated many parts of NGOSS to make it
practical—including in the area of information modeling, process analysis, and con-
tract definition. This book further elaborates NGOSS by examining the challenging
area of interface design.
One of the costs of deploying a new service is the cost of integrating all the
necessary applications into an effective software solution to manage the service.
This cost has been dubbed the “integration tax” and can turn out to be five times the
capital cost of procuring the management software in the first place.
From their long experience of the design and standardization of management
applications, the authors have extracted a core set of design patterns for the devel-
opment of effective and consistent interfaces to management applications. Adopting
these patterns across the industry could reduce the learning curve for software de-
velopers and allow service providers and systems integrators to rapidly and reliably
deploy management solutions and thereby markedly reduce the integration tax.
In a clear and concise way, the authors not only present the various technical
aspects of each pattern, but also the management context in which the patterns could
be used. The implementation examples of the patterns in two software technologies
demonstrate the practicality of their approach.
This book makes a valuable contribution to the growing body of knowledge con-
cerning the development of management solutions for telecommunications; I hope
you enjoy reading it.
Ireland, April 2009 Martin J. Creaner

President, TM Forum
vii
Preface
About this Book

The explosion of telecommunications services has thrust telecommunications
management into the forefront of the drive for effective service delivery. Once
viewed as a necessary evil, Operations Support Systems (OSSs), and the OSS ap-
plications they host, are now seen by service-providers as strategic components in
their on-going efforts to deliver superior customer service.
Developing OSS applications—those applications that carry out dedicated man-
agement tasks—is a challenging software undertaking. The challenge comes from
the size and heterogeneity of networks; the inherent complexity of communications
technologies; and the levels of security and reliability demanded by customers and
regulators. Hence, over the last twenty years, software engineers have necessarily
turned to the latest software tools, techniques, and standards to meet the challenge.
This has led to a proliferation of incompatible interface designs and underlying mod-
els making the integration of OSS applications into OSS solutions difficult and error
prone.
In this book, we advocate that the OSS community agree on a set of design
patterns to guide the development of interfaces to OSS applications thereby greatly
reducing the so-called “integration tax” paid by service providers in rolling out a
new service.
We offer a proven set of design patterns and best practices for the development of
consistent and effective interfaces to Operations Support Systems and the manage-
ment applications they host. The book is the distillation of many years of experience
in developing and deploying telecommunications management applications.
Audience
The primary audience for this book is software engineers and architects who are
responsible for the design of telecommunications management systems and for sys-
tem integrators who are responsible for the development of management solutions.
Software development managers and network managers will also find the book use-
ful.
ix
x Preface
Organization of the Book

In the first two chapters of the book, we layout the telecommunications manage-
ment landscape—including the driving forces and typical OSS architectures—and
make the case for a pattern-based approach to the design of OSS interfaces. In the
subsequent chapters we describe a number of architectural and programming pat-
terns important to the design of OSS interfaces, and give examples of their imple-
mentation using various software development environments.
Goals
The main goal of the book is to present a compelling case for the adoption of
a core set of design patterns across the OSS community that will help in the rapid
delivery of effective and reliable management solutions. We support our case by
focussing on a consistent presentation format, discussion of the relevance of each
pattern to telecommunications management, and extensive code examples. We hope
that the patterns will contribute to the growing ecosystem of best practices and stan-
dards, common code, and proven designs for OSS applications and their interfaces.
Aylmer, Quebec and Ottawa, Ontario Pierre Gauthier

April 2009 Colin Ashford
Acknowledgements
It is both customary, and it gives us great pleasure, to have this opportunity to thank
all those who made this book possible. First those who reviewed the various drafts
of the book and made so many useful recommendations: Adam Boyle, Eric Dil-
lon, Craig Gallen, Philippe Lalande, Tony Richardson, and Mike Kelly. Special
thanks are due to Eugene Deery for going well beyond the call to keep us hon-
est and to Anne Jones for proof reading our text at short notice. Thanks are also
due to Martin Creaner for writing the foreword and for permission to use the TM
Forum’s Business Process Framework Map. We would also like to thank the team
at Springer, Christoph Baumann and Carmen Wolf, for their editorial support and
Frank Holzwarth for his help in cheerfully answering all our question on LATEX.
Despite the combined efforts of all these people, any errors or omissions that
remain are the responsibility of the authors.
xi
Contents
1 Managing Telecommunications Services . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1 Telecommunications Management Systems Overview . . . . . . . . . . . . 1
1.2 The Management Challenge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3 A Pattern Approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.4 Telecommunications Management Requirements . . . . . . . . . . . . . . . . 5
1.5 OSS Reference Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.6 OSS Systems Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.7 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2 Designing Management Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.1 Developing an OSS Systems Architecture . . . . . . . . . . . . . . . . . . . . . . 11
2.2 Developing Management Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.3 OSS Reference Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.4 Remote Operations Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.5 The OSS Implementation Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.6 The Managed-Entity Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.7 OSS Design Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.7.1 Documenting OSS Design Patterns . . . . . . . . . . . . . . . . . . . . . 21
2.8 The Simple Inventory OSS Application . . . . . . . . . . . . . . . . . . . . . . . . 22
2.9 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3 OSS Architectural Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

3.1 Managed-Entity Value Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.2 OSS Façade Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.3 OSS Event Notification Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3.4 OSS Iterator Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
3.5 OSS Factory Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
3.6 OSS Discovery Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
3.7 OSS Named-Procedure Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
xiii
xiv Contents
3.8 OSS Command–Status Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

3.9 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
4 OSS Programming Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

4.1 Managed-Entity Key Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
4.2 Managed-Entity Life Cycle Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
4.3 Managed-Entity Update Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
4.4 Managed-Entity Attribute Population Pattern . . . . . . . . . . . . . . . . . . . 91
4.5 Managed-Entity Template Filter Pattern . . . . . . . . . . . . . . . . . . . . . . . . 95
4.6 Managed-Entity Bulk Update Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . 100
4.7 Last Update-Version-Number Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . 104
4.8 Final Thoughts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
A Type Definitions for the Simple Inventory . . . . . . . . . . . . . . . . . . . . . . . . . 107

A.1 OSS Session Profile Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
A.2 OSS Message Profile Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
B Implementing an OSS Client Using JAXB . . . . . . . . . . . . . . . . . . . . . . . . . 121

B.1 Create Equipment Record Managed-Entity Example . . . . . . . . . . . . . 121
B.2 Message Profile Implementation Software Architecture . . . . . . . . . . . 125
B.3 Create Equipment Record Managed-Entity Example—Complete
Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
C Binding the OSS Patterns to Web Services . . . . . . . . . . . . . . . . . . . . . . . . 131
D OSS Design Pattern Interaction and Usage . . . . . . . . . . . . . . . . . . . . . . . . 135

D.1 OSS Design Pattern Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
D.2 OSS Design Pattern Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
About the Authors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Colophon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Acronyms
BPF TM Forum Business Process Framework

CDMA Code Division Multiple Access
CIM Common Information Model
CRM Customer Relationship Management
CRUD Create Read Update Delete
DMTF Distributed Management Task Force
DSL Digital Subscriber Loop
EJB Enterprise Java BeansTM
EMS Element Management System
GSM Global System for Mobile Communications
IETF Internet Engineering Task Force
IPTV IP Television
JEE Java Platform, Enterprise EditionTM
JMS Java Message ServiceTM
LTE Long-term Evolution
MIB Management Information Base
NE Network Element
OSS Operations Support System
PC Personal Computer
RPC Remote Procedure Call
SOA Service Oriented Architecture
UDDI Universal Description Discovery and Integration
XML eXtended Markup Language
xv
Chapter 1
Managing Telecommunications Services
The world is disgracefully managed, one hardly knows to whom

to complain.
Ronald Firbank
Most of what we call management consists of making it difficult

for people to get their work done.
Peter Drucker
The growth of telecommunications services over the last twenty years has been
driven by two major innovations: mobility and broadband data. Mobile technologies
like GSM and CDMA have made mobile voice-services ubiquitous in most urban
centres around the world, and the emergence of higher-bandwidth mobile technolo-
gies, such as UMTS and LTE, are enabling new services like mobile email, video
to the handset, and web browsing. Similarly broadband data-services like DSL and
Fiber-to-the-Home have enabled new services such as high-speed internet access,
audio and video downloading, and IPTV. Using their existing approaches, telecom-
munications service-providers are having difficulty in managing these new tech-
nologies and services.
Customers are demanding ever-increasing levels of service: they expect that ser-
vices, whether fixed or mobile, be always available, that new service offerings be
rapidly deployed, and that service-level agreements be honoured. At the same time
fierce competition is putting pressure on prices and customer loyalty. Thus prudent
service providers are looking to cut costs by managing their networks more effi-
ciently and increasing their revenue by rolling out new services more quickly.
In this chapter we will look at the elements that go to make up a telecommunica-
tions management deployment and the challenge that service providers face in man-
aging telecommunications networks. We will go on to develop a reference model
for telecommunications management that will form a basis for the patterns that we
will discuss in the rest of the book.
1.1 Telecommunications Management Systems Overview
Telecommunications management systems are almost inevitably geographically dis-

tributed in nature primarily because the resources of telecommunications networks
that need to be managed are, themselves, distributed.
1
2 1 Managing Telecommunications Services
However, there are a number of other advantages to distributed management-

systems including:
• Supervision of the network and services can be moved from location to location,
say, to consolidate supervision outside of business hours.
• Management systems can be made of heterogeneous computer systems—cost-
effective PCs to access management applications and large servers or even main-
frames to host management applications.
• Management systems can grow incrementally—servers and workstations can be
added as required.
• Hosting of OSS applications can be centralized on servers in a few locations
where the applications can be more easily maintained.
Of course distributed systems come with some disadvantages—mainly the cost of
communications; we will address this issue in later chapters of the book.
Fig. 1.1 Telecommunications Management Systems Deployment
In Fig. 1.1 we illustrate the main parts of a telecommunications management

deployment. The main elements are as follows:
Operator systems are workstations that host the user interface and applications
that support the human operators in carrying out their management tasks. Operator
systems connect to remote Management Integration Systems and Operations Sup-
port Systems via a network in a client-server arrangement.
Management Integration Systems are servers that host management-integration
applications.
1.2 The Management Challenge 3
Operations Support Systems (OSSs) are servers that host OSS applications.
Managed systems are computer systems that host or manage managed resources.
Managed resources are logical or physical assets that provide services within the
telecommunications network and are manageable; examples of managed resources
include connectivity resources, end-user applications, and support resources.
Management-integration applications are software components that coordinate
the functionality of OSS applications to deliver management solutions.
OSS applications are software components that manage a particular aspect of a
telecommunications system such as a connectivity resource, an end-user applica-
tion, or a support resource; OSS applications implement the management logic and
business rules derived from an analysis of the management requirements.
Operator systems are generally cost-effective workstations or PCs that engage,
via the network, with one or more Management Integration Systems or with one or
more OSSs in a client-server style. As we will see later, operator systems can also
engage with OSSs in a publish-and-subscribe style to receive event notifications.
OSS applications typically implement a single management function, and come
from three main sources:
• Independent software vendors offering applications such as trouble ticketing,
alarm management, and service activation.
• Service providers who develop in-house applications to support specific aspects
of their business.
• Telecommunications-equipment vendors providing vendor- and equipment-specific
applications such as configuration, performance monitoring, and fault reporting.
As we shall see in the next section, a major part of deploying any new telecommuni-
cations service is integrating the various OSS applications into an effective manage-
ment solution. A management solution is a coordination of manual procedures and
the functionality of OSS applications that addresses a particular management prob-
lem; examples include service fulfillment, problem resolution, and provisioning of
network facilities.
1.2 The Management Challenge
A management solution is typically developed by integrating, in an integration ap-

plication or operator-support application, the functionality of a number of, normally
remote, OSS applications through their respective integration interfaces. For exam-
ple, a service fulfillment management solution—say to fulfill a customer request for
DSL service—will require engaging a number of OSS applications. These applica-
tions might include: an inventory application; an equipment-configuration applica-
tion; and an order-management application. Developing the management solution
will likely also require the development of some custom software to implement the
solution workflow and logic and to manage any operator interactions required.
However, not all OSS applications are built on compatible software and hard-
ware platforms, expose consistent interface styles, expose consistent models of the
resources to be managed, or use the same communications or database technologies.
These differences make it more difficult for a systems integrator or service provider
to integrate OSS applications into a management solution.
Over the years, a number of industry initiatives to reduce integration costs by
means of specifying standardized interfaces to OSS applications have been at-
tempted. Each has been based on detailed models and the particular implementation
technologies that were available at the time. Many initiatives have been quite suc-
cessful but, given the demanding nature of telecommunications management, there
has been an inevitable trend to re-write the standards using newer (and hopefully
better) technologies. Initiatives to standardize OSS application interfaces continue
today with the latest software technology offerings—Web Services and Service Ori-
ented Architectures (SOA). Although the technology may change, the core software
issues of designing effective, consistent interfaces to OSS applications remain.
1.3 A Pattern Approach
Our experience in both OSS-applications development and standardization over the

last twenty-five years, has led us to the conclusion that, given the increasing de-
mands made of telecommunications management, the industry must take advantage
of newer software technologies as they become mature and, at the same time, make
systems integration easier. We believe that this can be done by the industry’s coa-
lescing around agreements based on a more abstract style of specification of inter-
faces to OSS applications. In this book we describe a set of proven, OSS-specific
interface design patterns that set an architectural direction for OSS interface de-
sign for new software technologies and facilitate systems integration with existing
technologies.
A design pattern captures, in a technology-neutral manner, the essence of a
proven and practical solution to a recurring programming or architectural problem.
A design pattern is not a finished software specification, but rather a guide to how the
specification should be drawn up. To complete the specification, the design pattern
needs to be bound to a particular software technology to be implemented.
An agreement on a core set of design patterns to help in the design of OSS inter-
faces will greatly improve the ability of systems integrators to rapidly develop re-
liable management solutions whilst having to contend with different software tech-
nologies.
In the following sections of this chapter, we will introduce two models that will
form the basis of our pattern-based approach, but first we will discuss the require-
ments of managing telecommunications services.
1.4 Telecommunications Management Requirements 5
1.4 Telecommunications Management Requirements
Fig. 1.2 The TM Forum Business Process Framework Operations Map
Telecommunications management requirements1 are, at a high level, remarkably

consistent whether the service provider is a small internet service-provider or a large
common-carrier. The TM Forum[1] has captured these requirements in a process
framework called the Business Process Framework (BPF)[2]. The TM Forum BPF
classifies the business processes of a service provider into three major areas, namely:
Strategy, infrastructure, and product covering planning and life cycle manage-
ment of services and infrastructure.
Operations covering the core of operational management.
Enterprise management covering corporate support management such as finan-
cial management, enterprise risk management, and corporate effectiveness manage-
ment.
The relationships between the processes in each area are represented by a map;
the map for the Operations area, which will be our focus, is shown in Fig. 1.2. The
processes depicted vertically (Operations Support & Readiness, Fulfillment, Assur-
ance, and Billing) represent a high-level view of flow-through operational activities,
whereas the processes depicted horizontally (Customer Relationship Management,
1 Often referred to collectively as the business problem.

Service Management & Operations, Resource Management & Operations, and Sup-
plier/Partner Relationship Management) represent high-level business-related activ-
ities. These processes are successively decomposed into more detailed processes
that will form the basis of the OSS Reference Model which we will describe in the
next section.
1.5 OSS Reference Model
In order to better understand a class of system requirements and solutions (in our
case those of telecommunications management), it is often useful to develop a ref-
erence model. A reference model is an accepted functional decomposition based on
a class of requirements; the parts of the model cooperate to meet the requirements.
It is an important tool in helping to move from a particular system requirement to a
solution.
Fig. 1.3 OSS Reference Model
The OSS Reference Model shown in Fig. 1.3 is a five-layer model that decom-
poses functional aspects of management solutions. It is based on a layered model
shown in Marinescau[3]; the functional partitioning is as follows.
Presentation layer is responsible for all aspects of interfacing with operators such
as network managers, craft technicians, or customer-service representatives.
Operator-support layer is responsible for operator-task workflow and validation
of operator input; it delegates all requests for management functionality to either the
OSS integration layer or directly to the OSS application layer. Examples of operator
tasks are resolving trouble-tickets, simple configuring, and event report alerting.
1.6 OSS Systems Architecture 7
OSS integration layer is responsible for coordinating various OSS applications

to realize a management solution and for adapting existing operator applications.
Examples of management solutions include problem resolution, end-to-end config-
uration, and service fulfillment. The OSS integration layer realizes this coordination
by calling on the OSS application layer.
OSS application layer is responsible the OSS-application functionality derived
from an analysis of specific management requirements, and provides a consistent
view of the management aspects of managed resources. OSS application functional-
ity includes inventory management, trouble-ticket management, connectivity man-
agement, and management of end-user applications.
Adaptation and persistence layer is responsible for adapting the managed re-
sources to the view required by the OSS application layer and persisting the man-
agement state of the network.
1.6 OSS Systems Architecture
As we have noted in Sect. 1.1, telecommunications management systems are well

suited to be implemented in a distributed, client-server architectural style. In this
section we will develop a typical systems architecture based on the OSS Reference
Model. The OSS Systems Architecture (see Fig. 1.4) is the architecture of the system
that is actually deployed and models the implementation of the various layers of the
OSS Reference Model. We will describe the various parts of the architecture in the
next subsections.
Fig. 1.4 OSS Systems Architecture
Operator system is a workstation that hosts the implementation of the presenta-

tion and operator-support layers; the presentation layer might be implemented by a
simple command-line interface or a sophisticated graphical interface. The operator-
support layer is implemented by an operator-support application that engages with
either an OSS application or with a management integration application. Opera-
tor applications can be developed as applets or using traditional programming lan-
guages.
Management Integration System is a server that hosts the implementation of the

OSS integration layer in the form of integration applications or adaptors to ex-
isting operator applications. The applications and adaptors engage with OSS ap-
plications to access the latters’ functionality. The applications and adaptors might
be implemented by Enterprise Java Beans (EJBs)[4], CORBA objects[5], or Web
Services[6].
Operations Support System (OSS) is a server that hosts the implementation of
the OSS Application layer in the form of one or more specific OSS applications; the
applications might be implemented by Enterprise Java Beans (EJBs)[4], CORBA
objects[5], or Web Services[6].
Managed system is a computer system that hosts or manages managed resources;
managed systems can be Element Management Systems (EMSs) that manage one
or more connectivity resources or can be systems that host support resources or
end-user applications.
Managed resource is a logical or physical asset that provides a service within the
telecommunications network and is manageable; examples of managed resources
include connectivity resources, end-user applications, and support resources.
OSS client is an application that engages with a remote OSS application to access
the latter’s functionality.
The OSS Systems Architecture depicted in Fig. 1.4 is a typical implementation of

the OSS Reference Model, but could be modified in various ways, including: OSS
applications calling OSS applications in other OSSs or management-integration ap-
plications calling applications in other OSSs.
1.7 Summary
In this chapter we have reviewed some of the forces driving the development
of telecommunications management systems and indicated that successful service
providers are those that see telecommunications management as a strategic tool to
improve service delivery and not as a necessary evil. We have also introduced two
models that underpin telecommunications management. In the next chapter, we will
talk about how these models are used in designing the software for management
solutions.
References 9
References
1. TM Forum, www.tmforum.org.
2. Business Process Framework, TM Forum,
http://www.tmforum.org/BusinessProcessFramework/1647/home.html.
3. Marinescu, F., EJB Design Patterns. Wiley, New York, 2002. p. 128.
4. Enterprise Java Beans, Sun Developer Network, http://java.sun.com/products/ejb.
5. Common Object Request Broker, Object Management Group,
http://www.omg.org/gettingstarted/corbafaq.htm.
6. Web Services, World Wide Web Consortium, http://www.w3.org/2002/ws.
Chapter 2
Designing Management Solutions
I’m very good at integral and differential calculus;

I know the scientific names of beings animalculous:
In short, in matters vegetable, animal, and mineral,
I am the very model of a modern Major-General.
W. S. Gilbert
The OSS Reference Model we discussed in the previous chapter is a useful func-
tional way of thinking about management solutions; however, we need to turn this
functional view into a software architecture that allows us to develop and deploy
an OSS systems architecture that delivers the management solution. A typical OSS
client (either an operator-support application or a management-integration appli-
cation), will implement a management solution by engaging with one or more OSS
applications running on one or more OSSs. For example, a service-fulfillment appli-
cation supporting a customer-service agent in fulfilling a customer request for DSL
service might access an inventory application to query availability, a DSL EMS
to provision and activate the DSL multiplexer, and a billing application to initiate
billing.
It is the style of the engagement between the OSS client and the OSS application,
that is, the style of the interface exposed by the OSS application, that will concern
us for most of this chapter. But first we will review the process of developing an
OSS systems architecture.
2.1 Developing an OSS Systems Architecture
In Fig. 2.1, we illustrate the process of developing an OSS systems architecture;

the process is based upon an approach described in Bass et al.[1]. It consists of two
main steps:
1. Developing a reference architecture that sets the architectural direction of the

systems architecture.
2. developing a software architecture—a specification of the systems architecture
that will address the particular management problem; for example, the service-
fulfillment problem.
The OSS Reference Architecture is essentially a mapping of the OSS Reference

Model into software components; the mapping represents a refinement of the archi-
11
12 2 Designing Management Solutions
tectural style and sets a consistent architectural direction for system implementa-
tion. The software architecture is a combination of design patterns (the subject of
this book), a related information model, the OSS Reference Architecture, an imple-
mentation profile, and a binding to a particular software technology. The software
architecture is a specification of the systems architecture that will be deployed to
solve the management problem. We will now look at these various items in detail.
Management requirements a statement of general telecommunications-manage-
ment requirements systems must meet. The TMF Business Process Framework Op-
erations Map (see Sect. 1.4), is a key industry source for telecommunications man-
agement requirements.
OSS Reference Model a functional decomposition that meets telecommunication-
management requirements. It is a division of functionality and the data flows be-
tween the divisions. The OSS Reference Model, developed in Sect. 1.5, is the model
that we shall use as a basis for our discussions.
Fig. 2.1 Systems Architecture Development Process
Architectural style an abstract description of software components and the pat-

tern of runtime control and data transfer; as we will see in Sect. 2.3, OSS systems
architectures are best implemented using client-server and publish-and-subscribe
architectural styles.
Management problem a statement of the particular telecommunications-manage-
ment problem to be solved; for example, the service-fulfillment problem.
OSS Reference Architecture a refinement of an architectural style in terms of
interaction patterns, granularity of operation, and client-server separation; it is a
mapping of the OSS Reference Model into the architectural style. We will describe
the OSS Reference Architecture in more detail in Sect. 2.3.
OSS Design Pattern a description of an abstract architectural or programming so-
lution to a telecommunications management problem that has proven successful in
practice; adherence to OSS Design Patterns and to the OSS Reference Architecture
helps to ensure a consistent software architecture across OSS applications.
2.2 Developing Management Solutions 13
Information model a model of information elements, their inter-relationships, and

their behaviour. The TM Forum’s Information Framework[2] is a comprehensive
information model for telecommunications management; others include the DMTF
CIM model[3] and various MIBs defined by the IETF[4].
Implementation profile a description of the non-functional aspects of the style of
engagement between an OSS client and an OSS application.
Software architecture the specification of the systems architecture in terms of
programming and data elements bound to a particular software technology such
as JEE[5] or .NET[6].
Systems architecture the architecture of the system that is actually deployed; it
may be a direct realization of the software architecture, but may also be comple-
mented by deployment considerations such as clustering and virtualization.
2.2 Developing Management Solutions
Systems architectures that deliver management solutions lend themselves well to a

client-server style of implementation because of the distributed nature of telecom-
munications management. To develop a client-server-style OSS systems architec-
ture from scratch would, in principle, require developing the clients to the OSS ap-
plications (either the operator-support applications or the management-integration
applications) and the required OSS (server) applications.
Now, in practice, most OSS applications will already exist: equipment suppliers
will have delivered EMSs with their transmission and switching equipment and ser-
vice providers will have already invested in inventory, trouble ticketing, and billing
applications. So developing a new systems architecture to deliver a management so-
lution is largely a question of developing the OSS clients (either the operator-support
applications or the management-integration applications).
An OSS client may need to engage with a number of OSS applications to address
a particular management problem. Having a consistent engagement style across ap-
plications will greatly reduce the learning curve associated with interfacing to each
application and help in the rapid development of more reliable implementations.
Below we list the criteria that are important in achieving a consistent engagement
style and the choices that we have found useful:
• A consistent model of the resources to be managed (the Managed-Entity Model,
see Sect. 2.6).
• A consistent style of modifying resource models by clients (CRUD see Sect. 2.6
and the OSS Façade pattern, see Sect. 3.2).
• A consistent style of identifying resource models (Managed-Entity Key pattern,
see Sect. 4.1 and Managed-Entity Template Filter pattern, see Sect. 4.5).
• A consistent style of information exchange between OSS clients and OSS appli-
cations (Remote Operations Model, see Sect. 2.4; Managed-Entity Value pattern,
see Sect. 3.1; and OSS Event Notification pattern, see Sect. 3.3).
• Consistent rules on the non-functional aspects of information exchange between
OSS clients and OSS applications (OSS Implementation Profiles, see Sect. 2.5).
• A consistent query mechanism (OSS Named-procedure pattern, see Sect. 3.7).
In our experience, meeting these requirements will reduce integration and develop-
ment time, reduce errors, and reduce training costs.
In the next section we will show how many of these criteria can be captured in
a reference architecture that we will use as the basis for discussing the OSS Design
Patterns in the next chapters of the book.
2.3 OSS Reference Architecture
As we saw in Sect. 2.1, a reference architecture is a mapping of a reference model

into software components based on a particular architectural style. The reference
architecture we have found useful is illustrated in Fig. 2.2.
Fig. 2.2 OSS Reference Architecture
We will discuss each of the parts of the reference architecture in the following
sections:
OSS client an application that engages with a remote OSS application to access the
latter’s functionality employing a client-server style for operations and a publish-
and-subscribe style for notifications.
OSS Façade a view, in terms of remote operations, exposed by an OSS applica-
tion; applications that present similar styles of façade are more easily integrated,
see Sect. 3.2.
2.4 Remote Operations Model 15
Notification service a software component that delivers event reports asynchronously

to OSS clients. In Sect. 3.3 we will discuss a publish-and-subscribe notification ser-
vice.
OSS application a software component that manages a particular aspect of a
telecommunications system such as a connectivity resource, an end-user applica-
tion, or a support resource.
Managed entity a model of the management aspects of managed resource; it is by
engaging with a managed entity that the corresponding managed resource is man-
aged.
Managed resource a logical or physical asset that provides a service within the
telecommunications network and is manageable; examples include connectivity re-
sources, end-user applications, or support resources.
Other OSS applications OSS applications hosted on other systems.
A reference architecture is technology neutral so, to develop the software architec-

ture, the reference architecture must be bound to a specific software technology such
as JEE[5], JMS[7], Web Services[8], or .NET[6].
2.4 Remote Operations Model
The Remote Operations Model models the way a client can invoke operations on a
remote application. The remote operations model defines three interactions between
a client and a remote application:
• a named request, possibly including some calling arguments;
• a response, possibly with return arguments, indicating a normal completion; and
• one or more named exceptions, possibly including return arguments, indicating
an abnormal completion.
Fig. 2.3 Remote Operations
The client invokes a remote operation by sending a request to the application,

and then waits for a response or exception to be returned. The exception indicates
an abnormal termination of the remote operation perhaps due to incorrect invocation
parameters, a failure of the remote host, or a communications failure.
The remote operations model can operate in:

• a synchronous mode, based on a Remote Procedure Call (RPC) model, where the
client blocks until the response or exception is received; or
• an asynchronous mode, based on a messaging model, where the client continues
to execute after making the invocation, but has made arrangements to process the
response or exception when it arrives, generally by providing a call-back address.
Remote operations are documented in terms of operation signatures: operation
signatures specify the operation name, any calling argument-types and any return
argument-types (both for normal responses and exceptions).
In the next section, we will see how these modes are used to meet different non-
functional requirements of interfaces to OSS applications.
2.5 The OSS Implementation Profiles

In the design of OSS integration interfaces, coupling and performance are important
non-functional requirements that have to be taken into account. Performance of an
integration interface is a measure of rate of invocation of operations across the in-
terface; coupling is a measure of the implementation inter-dependence between the
OSS client and the OSS application.
Integration interfaces that are tightly coupled, for example, those where the OSS
client and the OSS application have been developed using the same software tech-
nology (e.g. Java Remote Method Invocation), are likely to exhibit higher perfor-
mance because there is less processing involved in operation invocation and re-
sponse. However, tightly-coupled interfaces are generally more brittle in the face
of changes to OSS applications and, OSS clients generally require modification,
recompilation, and redeployment to accommodate application changes.
Conversely, interfaces that are loosely coupled, for example, those where the
OSS client and the OSS application have been developed using different software
technologies and are interfaced using, say, XML messages, are likely to exhibit
lower performance because of the overhead of processing of the XML. However,
OSS applications that are loosely coupled are generally more easily integrated and
are less brittle in the face of OSS application changes—OSS clients can often use
message inspection and introspection to accommodate application changes.
For OSS applications, we recognize two categories of integration interfaces:
• High-performance interfaces typically for the real-time management of the net-
work (configuration, alarm monitoring, etc.).
• Flexible interfaces to support intra- and inter-company application integration
(service activation, trouble-ticket management, etc.).
To support these two categories, we will describe two implementation profiles that
characterize the non-functional aspects of the reference architecture. We have found
these profiles useful in developing interfaces to OSS applications; we call these
profiles the OSS Session Profile and the OSS Message Profile. The characteristics
of the two profiles are summarized in Table 2.1.
2.5 The OSS Implementation Profiles 17
OSS Implementation Profiles

OSS Session Profile OSS Message Profile
Characteristic
Temporal Session-oriented Sessionless
Coupling Tight Loose
Asynchronous message
Remote Operations Mode Synchronous RPC
exchange
Encoding Style Binary Text
Managed-Entity Value-type Object Document
Interface Definition Style API Message schema
Example Operation Binding JEE JMS (XML)
Notification Style Publish-and-subscribe Publish-and-subscribe
Example Notification JMS (ObjectMessage) JMS (TextMessage)
Binding
Table 2.1 The Characteristics of the OSS Implementation Profiles
OSS Session Profile

The OSS Session Profile is designed to meet the needs for high-performance in-
terfaces between OSS clients and OSS applications. Remote operations are imple-
mented in a session-oriented, synchronous RPC style. (The client first sets up a ses-
sion with the OSS application to build a stub to communicate with the application;
the client then uses that stub for one or more remote procedure calls.) The remote
procedure call types are documented in terms of an Application Programming In-
terface (API). The notification style is a publish-and-subscribe message style.
A synchronous, RPC style of interface has a number of advantages, including:
• A simple programming model for clients—one based on the well-known proce-
dure call model.
• Low invocation overhead because the interface is optimized to a particular soft-
ware technology or platform.
• An efficient, binary encoding of the data transfered between the client and the
application.
However it suffers from a number of disadvantages including that:
• Clients are brittle in the face of OSS application changes.
• System administrators must make special arrangements for operations to pass
through firewalls.
• Bridging must be used to support notifications from other OSS applications.
We will use Java Platform, Enterprise Edition (JEE)[5] to illustrate the bind-
ing of patterns to technology in the session profile. The binding of the reference
architecture to JEE is shown in Fig. 2.4: the faca
¸ de is implemented by an Enter-
prise Java Bean (EJB) session bean, and the notification service is implemented
by a Java Message Service (JMS) [7]. Operation and notification signatures and
argument types are declared in terms of Java methods and Java data types (i.e. a
Java-style API).
Fig. 2.4 Binding the OSS Session Profile to JEE
OSS Message Profile

The OSS Message Profile is designed to meet the need for flexible intra- and inter-
company application integration. Remote operations are realized in an asynchronous
style: the client sends messages to a message queue and specifies a destination
for the reply. The message types are documented using a schema. The notification
style is a publish-and-subscribe style message style; the message types are also doc-
umented using a schema.
An asynchronous, message-oriented, interface has a number of advantages, in-
cluding:
• The client is not blocked waiting for the OSS application to complete the request
and return the result.
• The interface is less brittle in the face of changes to OSS applications.
• Easier integration because the text-encoding and document-oriented styles.
• The receiver (either the OSS client or the OSS application) does not need to be
available when the message is sent.
Fig. 2.5 Binding the OSS Message Profile to JMS
However, these advantages come at the expense of a more complicated program-

ming model and processing overhead.
We will use JMS to illustrate the binding of patterns to technology in the message
profile. The binding of the reference architecture is shown in Fig. 2.5: the faca ¸ de
is implemented by a JMS queue and a message-driven bean, and the notification
service is implemented by JMS using a JMS topic to publish specific event types.
2.6 The Managed-Entity Model 19
Operation and notification signatures and argument types are specified in terms of
XML document types and XML data types respectively using the XML Schema
Language[9]. In Appendix C we discuss a binding of the message profile to Web
Services.
2.6 The Managed-Entity Model
The resources that we want to manage, that is the managed resources, may take
many forms, for example: a record in an inventory, a line card in a network ele-
ment, or a trouble ticket in a trouble ticketing system. In developing management
solutions, it is helpful to have a consistent model of the management aspects of man-
aged resources. The OSS Reference Architecture models the management aspects
of managed resources as managed entities. Managed entities are abstract software
entities that can be uniquely identified and expose a number of named attributes.
It is by reading and updating the attributes of the managed entities that the corre-
sponding managed resources are managed.
Referencing Managed Entities

In order to read or update the attributes of a managed entity, a client must first obtain
a reference to the managed entity. The Managed-Entity model allows two types of
references, namely:
• unambiguous references using a key; and
• references using an associative look-up.
A managed entity exposes an attribute, a key, that can be used to unambiguously
identify it within the context of an OSS application responsible for the managed en-
tity. The Managed-Entity model does not prescribe the structure of the key, only that
it can be used to uniquely identify a managed entity; for example in the operation
getInventoryRecordByKey() (see the Managed-entity Value pattern example in
Sect. 3.1, p. 32). The Managed-Entity model does not talk about the structure of
the key for pragmatic reasons—the structure of the key will probably be closely
tied to the mechanism used to identify the related managed resource—for example
a reference number for a trouble ticket or a hierarchical name for a piece of commu-
nications equipment. We discuss managed-entity keys in more detail in Sect. 4.1.
Whilst unambiguous references to managed entities are an obvious requirement
for managing telecommunications services, references to managed entities based
on their state—that is, an associative look-up—are very useful. For example a net-
work manager might want to review all the trouble tickets outstanding for a piece of
communications equipment. We discuss the form of associative look-up in detail in
Sect. 4.5.
Both the managed-entity key and the associative look-up mechanisms operate
within the context of an OSS application that is responsible for the managed entity;
this context is referred to as the OSS Application Context. To engage with a managed
entity, the OSS client must first locate the appropriate application context and then
use either a key or an associative look-up to obtain a reference to the particular
managed entity. A OSS Application Context could, for example, be a session bean,
a JMS queue, or a Web Services endpoint.
Updating Managed Entities

The modification of managed-entity attributes (and the creation and deletion of man-
aged entities) by clients is carried out according to a Create, Read, Update, Delete
(CRUD) model:
Create models the creation of managed resources;
Read models the reading of the attributes of managed resources;
Update models the updating of the attributes of managed resources; and
Delete models the deletion of managed resources.
For example, a trouble ticket (a managed resource in our reference architec-
ture) might contain an information field named status that denotes the status of the
ticket—say “outstanding” or “completed”. The managed entity modelling that trou-
ble ticket will have a corresponding attribute, likely named status, to model the
field in the trouble ticket. An OSS client can read the status attribute of the man-
aged entity to get a value corresponding to the status field of the trouble ticket; it can
also update the status attribute to update the status field of the trouble ticket. Simi-
larly, the creation and deletion of a managed entity modelling the trouble ticket will
cause the creation and deletion of the corresponding trouble ticket in the managed
system. It is the responsibility of the OSS application to synchronize the attribute
value in the managed entity with the corresponding information in the managed
resource.
Managed resources may also be managed by the invocation of non-CRUD oper-
ations on OSS applications for example, to restart a piece of equipment or reload a
database.
As we noted above, a managed entity is an abstract component, and the reference
architecture gives us no clue as to the implementation of the managed entity. So how
can we read or update attribute values? The answer is that, for every managed-entity
type, an application developer must define a surrogate—the managed-entity value
type. A managed-entity value-type is a data item bound to a particular software
technology. We will talk more about managed-entity values in Sect. 3.1.
2.7 OSS Design Patterns
Experienced software designers solve commonly-occurring problems by reusing so-

lutions that have proved successful in the past; design patterns are a way of capturing
such solutions so that other designers can take advantage of the design experience.
We shall use the same approach designing OSS interfaces: capture the essence of a
solution in a technology-neutral design pattern.
2.7 OSS Design Patterns 21
To be implemented, a pattern has to be bound to a particular software technology,

and we will show examples of bindings to JEE and JMS. The power of patterns is
that, in principle, they can be bound to any new software technology; Web Services
being a case in point (see Appendix C).
By making sure that integration-interface specifications adhere to an agreed set
of patterns, the task of integrating OSS applications will be eased: commonly-
occurring problems will be resolved in a common fashion. Whilst this will not en-
sure integration of OSS applications “out-of-the-box”, it will dramatically reduce
the effort required to integrate OSS applications into a management solution.
2.7.1 Documenting OSS Design Patterns
In the following chapters of the book, we will discuss a core set of over a dozen
patterns that we believe are fundamental to designing consistent OSS application in-
terfaces. These patterns are the distillation of many years of experience in the speci-
fication and standardization of OSS applications. They are not necessarily unique to
OSS applications; many are adaptations of patterns commonly found in distributed
systems—patterns such as the Façade Pattern, the Factory Pattern, and the Trans-
fer Object Pattern. In order to help readers quickly become comfortable with OSS
Design Patterns, we have adopted a format similar to that used by the Gamma et
al.[10]. We will describe each design pattern under the following headings:
Name a succinct encapsulation of the essence of the pattern—it should become
part of the OSS design vocabulary.
Intent a short statement of the rationale and intent of the pattern and the design
problem it solves.
Motivation a description or scenario that illustrates the problem the pattern ad-
dresses.
Solution a detailed description of the solution to the design problem, either in nar-
rative or graphical form.
Example fragments of code or schemata that illustrate how the design pattern
might be implemented and used in the context of the two implementation profiles.
We will use Java to illustrate the use of patterns in the session profile, and XML
Schema grammar and JMS in the message profile.
2.8 The Simple Inventory OSS Application
To illustrate the patterns, we will use a running example OSS application—the Sim-
ple Inventory OSS application. The Simple Inventory application implements (as its
name implies) a simple inventory of spare parts, and supports three record types:
• an equipment record type;
• an extended equipment record type; and
• a supplier record type.
The equipment record type contains the following fields:
Creation date the date the record was created;
Equipment type a short description of the type of equipment;
Number on hand the number of equipment items on hand;
Location the location of the equipment items; and
Record key a unique key to the record.
The extended equipment record type contains the following fields in addition to
those in the equipment record:
Re-order level the level of inventory triggering re-order; and
Supplier name the name of the preferred equipment supplier.
The supplier record type contains the following fields:
Creation date the date the record was created;
Name the name of the supplier;
Address the address of the supplier;
Contact number a contact telephone number; and
Record key a unique key to the record.
As we discuss the various patterns, we will introduce example code that an OSS
client might use to create records, delete records, read records, and update records
in the inventory.
2.9 Summary
In this chapter we have introduced a number of tools to help in the design of OSS
systems architectures: the design process, implementation profiles, the OSS Refer-
ence Architecture, and the Managed-entity model. This chapter builds on the pre-
vious one in setting the context for our pattern approach to the design of OSS in-
terfaces. In the next two chapters of the book, we describe in detail over a dozen
important OSS Design Patterns; the text will be accompanied code and schema ex-
amples to illustrate how a client might use the patterns.
References 23
References
1. Bass, L. and Kazman, R., Software Architecture in Practice. Addison Wesley Longman,
Reading, 1998.
2. Information Framework, TM Forum,
http://www.tmforum.org/InformationFramework/1684/home.html.
3. Common Information Model, Distributed Management Task Force,
http://www.dmtf.org/standards/cim.
4. Management Information Base, Internet Engineering Task Force, http://www.ietf.org.
5. Java Platform, Enterprise Edition, Sun Developer Network, http://java.sun.com/javaee.
6. .NET, Microsoft, http://www.microsoft.com/net.
7. Java Message Service, Sun Developer Network, http://java.sun.com/products/jms.
9. XML Schema, World Wide Web Consortium, http://www.w3.org/XML/Schema.
10. Gamma, E., Helm, R., Johnson, R., Vlissides, J., Design Patterns. Addison-Wesley, Reading,
1994.
Chapter 3
OSS Architectural Patterns
The physician can bury his mistakes, but the architect

can only advise his client to plant vines.
Frank Lloyd Wright
In this chapter we will introduce a number of architectural patterns that are useful
in designing the overall structure of OSS integration interfaces; they will set the
context for programming patterns that we will introduce in the next chapter. Of all
the architectural patterns, the Managed-Entity Value pattern and the OSS Façade
pattern are the two most important. The Managed-Entity Value pattern is the pattern
that is used by clients to read and update the attributes of managed entities (models
of the resources to be managed), be they trouble tickets or mobile base stations.
The OSS Façade pattern is the fundamental pattern used by clients to engage with
OSS applications—it packages the functionality offered by the OSS application and
makes it available in a consistent manner.
3.1 Managed-Entity Value Pattern
In the OSS Reference Architecture (see Sect. 2.3), the management aspects of man-
aged resources are modelled as managed entities and the information aspects of
managed resources are modelled as attributes of the managed entities. It is by read-
ing and updating the values of the attributes of the managed entities, that the cor-
responding managed resources can be managed. In order for OSS clients to easily
engage with multiple OSS applications, it is important that each application expose
a consistent read/update interface model.
Intent
Provide a mechanism to efficiently read and update the attribute values of managed
entities.
25
26 3 OSS Architectural Patterns
Motivation
The OSS Reference Architecture does not say how managed entities are to be im-
plemented nor how their attribute values can be read or updated. However, it is by
reading and updating the attributes of managed entities that managed resources are
managed. To help facilitate the development of management solutions, we need to
devise a consistent interface style across all OSS applications to read and update the
attribute values of managed entities.
Fig. 3.1 Managed-Entity Value Pattern
Solution
Adapt the Data Transfer Object pattern[1] to support the reading and updating of
the attribute values of managed entities. For each managed-entity type, define a
managed-entity value type, that acts as a surrogate for the managed entity and in-
stances of which can be transferred between the OSS client and the OSS application
(see Fig. 3.1).
To read and update the attributes of a managed entity, an OSS client requests
that a managed-entity value, corresponding to the managed entity of interest, be
transferred from the OSS application to the client’s address space. The managed-
entity value contains a copy, at that point in time, of the attribute values of the
managed entity. The client can read and update these copies in its local environment,
and subsequently can request that the managed-entity attribute values be updated by
sending an updated copy of the managed-entity value to the OSS application (see
Fig. 3.2 and Sect. 4.3).
An OSS client creates a managed entity by sending a suitably-populated managed-
entity value to the OSS application with a request to create the managed entity. We
deal with the creation (and deletion) of managed entities in detail in Sect. 4.2.
It is useful to arrange managed-entity value types in an inheritance hierarchy to
factor out common fields and produce a type hierarchy to take advantage of poly-
morphic operations. We discuss this in more detail in Sect. 4.2.
3.1 Managed-Entity Value Pattern 27
The Managed-Entity Value pattern is based on the Transfer Object pattern, and
shares a number of its advantages, including:
• It shields the OSS client from the actual implementation of the managed entity.
• It offers a consistent mechanism for reading and updating the attributes of a man-
aged entity.
• Field-level validation and integrity checking of attribute values can be accom-
plished in the local environment.
• By reading or updating a number of attributes of a managed entity in one go, it
reduces the network traffic and delay that would be associated with reading or
updating each attribute individually.
Fig. 3.2 Reading the Attribute Values of a Managed Entity Using a Managed-Entity Value
One of the consequences of the Managed-Entity Value pattern is that all of the
attribute values are transferred whether they are all needed or not. In the case of
a managed entity that has a large number of attributes, and where only a few are
required, this can lead to unnecessary consumption of bandwidth and poor response.
The Managed-Entity Attribute Population pattern can help alleviate the problem
(see Sect. 4.4).
Example
In the next sub-sections, we will show how managed-entity values are read in the
two OSS profiles. We will use for this, and all the other examples, the Simple In-
ventory application introduced in Sect. 2.8. The interface diagram for the Simple
Inventory value-objects is shown in Fig. 3.3.
Fig. 3.3 Simple Inventory Value-Object Interface Diagram
OSS Session Profile Example

In the OSS Session Profile, a managed-entity value is implemented as an object that
can be transferred between OSS client and OSS application. A client accesses a
managed-entity value by an interface that declares accessors/mutators (getters and
setters) to access the fields of the value object that correspond to the attributes of the
managed entity. Using Java, we declare the interfaces shown in Fig. 3.3 as follows.
First, the RecordKey interface:
/**
*
* Record-key inteface declaration
*/
public interface RecordKey extends java.io.Serializable {
/**
* Constants to identify the fields of
* the managed-entity record key
*/
public static final String RECORDTYPE = "RecordType";
public static final String RECORDID = "RecordId";
/**
* Accessors and mutators for fieldsSet
*/
public void setRecordId(String id);
public String getRecordId();
public void setRecordType(String type);
public String getRecordType();

}
The RecordKey interface above extends java.io.Serializable, declares acces-

sors/mutators for the two fields of the key value-object (RECORDTYPE and RECOR-
DID), and declares two constants to identify the two fields (see Sect. 4.1 for more
details of the use of these fields).
Next we define the ManagedEntityValue interface—the base interface declara-
tion for all managed-entity value objects:
/**
* Managed-entity value-object interface declaration.
*
* This the base interface for all managed-entity value-objects.
*/
public interface ManagedEntityValue extends java.io.Serializable {
//public interface ManagedEntityValue {
/**
* the managed-entity value-object
*/
public static final String LASTUPDATEVERSIONNUMBER =
"LastUpdateVersionNumber";
public static final String RECORDKEY = "RecordKey";
/**
* Managed-entity value is a factory for record keys
*/
public RecordKey makeRecordKey();
/**
* Accessors and mutators for fields
*/
public RecordKey getRecordKey();
public void setRecordKey(RecordKey key);
public long getLastUpdateVersionNumber();
public void setLastUpdateVersionNumber(long lastUpdateNumber);
/**
* Get managed-entity attribute/value pairs
*/
public java.util.Hashtable getAttributeValues(String[] names)
throws ApplicationException;
/**
* Get managed-entity attribute names
*/
public String[] getAttributeNames();
/**
* Attribute population methods
*/
public void unPopulate(String attributeName);
public boolean isPopulated(String attributeName);

}
The ManagedEntityValue interface above is the base interface declaration for

all managed-entity value objects; it declares the following fields and methods inher-
ited by all managed-entity value-object interfaces:
• Two constants, RECORDKEY (see Sect. 4.1) and LASTUPDATEVERSIONNUMBER (see
Sect. 4.7), to define the names of the fields in the value-object that correspond to
the names of the two attributes in the managed-entity.
• A factory method for making managed-entity keys—the ManagedEntityValue
interface is a factory for making managed-entity keys (see Sect. 3.5).
• Accessors/mutators to get and set the RecordKey value-object field.
• Accessors/mutators to get and set the LastUpdateVersionNumber value-object
field.
• A generic method for discovering the managed-entity attribute names and values
(see Sect. 3.6).
• A generic method for discovering the names of the managed-entity attributes (see
Sect. 3.6).
Next the InventoryRecordValue interface:
/**
* Inventory record value-object interface declaration.
*
* This the base interface for all Simple Inventory Record value-objects.
* The fields of the value object carry copies of the values
* of the attributes of the Inventory Record managed entities.
*/
public interface InventoryRecordValue extends ManagedEntityValue{
/**
* Constant to identify the field of
* the inventory record value-object
*/
public static final String CREATIONDATE = "RecordCreationDate";
/**
* Accessors for field
*/
public Calendar getRecordCreationDate();
}
The InventoryRecordValue interface above extends the ManagedEntityValue

interface, declares an accessor for the CREATIONDATE field of the value object, and
declares a constant to identify the field. The field in the value object corresponds to
an attribute in the managed-entity.
Next the EquipmentRecordValue interface:
/**
* Equipment record value-object interface declaration
*/
public interface EquipmentRecordValue
extends InventoryRecordValue {
/**
* Constants to identify the fields of the equipment record value-object
*/
public final static String EQUIPMENTTYPE = "EquipmentType";
public final static String NUMBERONHAND = "NumberOnHand";
public final static String LOCATION = "Location";
/*
* Accessors and mutators for the fields of the value-object
*/
void setEquipmentType(String equipmentType);
String getEquipmentType();
void setNumberOnHand(int numberOnHand);
int getNumberOnHand();
void setLocation(String aLocation);
String getLocation();
}
The EquipmentRecordValue interface above extends the InventoryRecordValue

interface, declares accessors/mutators for the three fields of the value object (EQUIP-
MENTTYPE, NUMBERONHAND, and LOCATION), and declares three constants to identify
the three fields. Each field in the value object corresponds to an attribute in the
equipment record managed-entity.
Next the ExtendedEquipmentRecordValue interface:
/**
* Extended-equipment record value-object interface declaration
*/
public interface ExtendedEquipmentRecordValue
extends EquipmentRecordValue {
/**
* Constants to identify the extended-equipment record
* fields (attributes)
*/
public final static String REORDERLEVEL = "ReorderLevel";
public final static String SUPPLIERNAME = "SupplierName";
void setReorderLevel(int reorderLevel);
int getReorderLevel();
void setSupplierName(String supplierName);
String getSupplierName();
}
The ExtendedEquipmentRecordValue interface above extends the Equipmen-

tRecordValue interface, declares accessors/mutators for the two additional fields
of the value object (REORDERLEVEL and SUPPLIERNAME), and declares two constants
to identify the two fields. Each field in the value object corresponds to an attribute
in the extended equipment record managed-entity.
And, finally, the SupplierRecordValue interface:
/**
* Supplier record value object interface
*/
public interface SupplierRecordValue
/**
* Constants to identify the fields of the supplier record value-object
*/
public final static String NAME = "SupplierName";
public final static String ADDRESS = "SupplierAddress";
public final static String CONTACTNUMBER = "ContactNumber";
/**
* Accessor and mutators for the fields of the value-object
*/
void setSupplierAddress(String supplierAddress);
String getSupplierAddress();
void setContactNumber(String aTelephoneNumber);
String getContactNumber();
}
The SupplierRecordValue interface above extends the InventoryRecord-

Value interface, declares accessors/mutators for the three additional fields of the
value object (NAME, ADDRESS, and CONTACTNUMBER), and declares three constants to
identify the three fields. Each field in the value object corresponds to an attribute
in the supplier record managed-entity. Using the getInventoryRecordByKey()
method defined in the OSS Façade pattern (see Sect. 3.2), the following snippet of
code prints out the values of an equipment record in the Simple Inventory using a
value object:
/*
* Print equipment record
*/
/*
* session = ... get a Simple Inventory session bean
* key = ... set the key to a previously-saved value and
* get the equipment record value-object identified by the key
*/
recordvo = (EquipmentRecordValue) session.getInventoryRecordByKey(key,

null);
// Print the values

System.out.println(recordvo.toString());
With a previously-saved key value, the client requests an equipment record value-
object from the session bean corresponding to the supplied key, and then prints out
the fields in the value object that correspond to attribute values of the equipment
record managed-entity. The output might look like this:
Equipment Record Value:

Record Id = 42
Record Type = EquipmentRecordType
LastUpdateVersionNumber = 1234
RecordCreationDate = 2009 4 1 12h15
EquipmentType = LineCard
NumberOnHand = 10
Location = Montreal
OSS Message Profile Example

In the OSS Message Profile, a managed-entity value is implemented as a document.
Using the XML Schema Language[3], we define complex types for the record key,
the managed-entity value-type, and for each of the four Simple Inventory record
types.
We first define the RecordKeyType complex type thus:

<complexType name="RecordKeyType">
<sequence>
<element name="recordId" type="string" nillable="false"/>
<element name="recordType" type="string" nillable="true"/>
</sequence>
</complexType>
We now define the base ManagedEntityValueType to factor out the common

elements <recordKey> and <lastUpdateVersionNumber>:

<complexType name="ManagedEntityValueType">
<sequence>
<element name="recordKey" type="entities:RecordKeyType"></element>
<element name="lastUpdateNumber" type="xsd:long" minOccurs="0"></element>
</sequence>
</complexType>
Using the <extension> element in XML Schema, we now define a complex

type for the inventory record value-type:

<complexType name="InventoryRecordValueType">
<complexContent>
<extension base="entities:ManagedEntityValueType">
<sequence>
<element name="creationDate" type="xsd:dateTime" minOccurs="0"></element>
</sequence>
</extension>
</complexContent>
</complexType>
Again, using the <extension> element in XML Schema, we now define com-
plex types for the equipment record, extended-equipment record, and supplier
record value-types. Each of the elements of the complex types (and those extended
from the inventory record value-type) correspond to an attribute of the respective
inventory record managed-entity.

<complexType name="EquipmentRecordValueType">
<complexContent>
<extension base="entities:InventoryRecordValueType">
<sequence>
<element name="equipmentType" type="string" minOccurs="0"/>
<element name="numberOnHand" type="int" minOccurs="0"/>
<element name="location" type="string" minOccurs="0"/>
</sequence>
</extension>
</complexContent>
</complexType>

<complexType name="ExtendedEquipmentRecordValueType">
<complexContent>
<extension base="entities:EquipmentRecordValueType">
<sequence>
<element name="reorderLevel" type="int"/>
<element name="supplierName" type="string"/>
</sequence>
</extension>
</complexContent>
</complexType>

<complexType name="SupplierRecordValueType">
<complexContent>
<sequence>
<element name="supplierName" type="string" minOccurs="0"/>
<element name="supplierAddress" type="string" minOccurs="0"/>
<element name="contactNumber" type="string" minOccurs="0"/>
</sequence>
</extension>
</complexContent>
</complexType>
We finally define four element types as the respective Simple Inventory value
document types.

<element name="inventoryRecordKey" type="entities:RecordKeyType"/>
<element name="managedEntityValue" type="entities:ManagedEntityValueType"/>
<element name="inventoryRecordValue" type="entities:InventoryRecordValueType"/>
<element name="equipmentRecordValue" type="entities:EquipmentRecordValueType"/>
<element name="extendedEquipmentRecordValue"
type="entities:ExtendedEquipmentRecordValueType"/>
<element name="supplierRecordValue" type="entities:SupplierRecordValueType"/>
An instance of a equipment record value document might look like this:

<entities:equipmentRecordValue
xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’
xmlns:entities=’http://xml.netbeans.org/schema/Entities’
xsi:schemaLocation=’http://xml.netbeans.org/schema/Entities file:...
<entities:recordKey>
<entities:recordId>42</entities:recordId>
<entities:recordType>EquipmentRecordType</entities:recordType>
</entities:recordKey>
<entities:lastUpdateNumber>1234</entities:lastUpdateNumber>
<entities:creationDate>2009-04-01T12:15:00-05:00</entities:creationDate>
<entities:equipmentType>LineCard</entities:equipmentType>
<entities:numberOnHand>10</entities:numberOnHand>
<entities:location>Montreal</entities:location>
</entities:equipmentRecordValue>
Summary
The Managed-Entity Value pattern provides a consistent and effective way of read-
ing and updating the attribute values of managed entities. The pattern is also used
in the creation of managed-entities and associative addressing of managed entities.
The value pattern is also used to invoke named operations and queries. By arranging
value types in type hierarchy, it is possible to exploit the polymorphic features of
software technologies such as Java and XML Schema.
3.2 OSS Façade Pattern
The Managed-Entity model gives an OSS client a consistent view of the attributes
of a managed entity and, by extension, the information aspects of the corresponding
managed resource. It is also important that OSS applications expose a consistent
view of their operational aspects.
Intent
That OSS applications expose a consistent view of their operational aspects.
Motivation
The primary operational aspects of an OSS application are the operations that sup-
port the read-update model of accessing managed entities (see Sect. 4.3). However,
there are other operational aspects that need to be supported such as the retrieval
of metadata and the creation of various objects and documents. In order to facili-
tate the efficient engagement of multiple OSS applications by an OSS client, OSS
applications should expose a consistent set of operations.
Solution
Define a canonical set of operations that supports the engagement between an OSS
client and an OSS application and package the operations in a façade. We will
adapt the Session Façade pattern[4] to provide such packaging. A façade to sup-
port telecommunications management should expose operations to at least:
• Create one or more managed entities given initial values for the attributes (see
Sect. 4.2).
• Read the attribute values of one or more managed entities selected by key or by
matching attribute values (see Sect. 4.3).
• Update the attribute values of one or more managed entities selected by key or
by matching attribute values (see Sect. 4.3).
• Create empty value objects such as keys, managed-entity values (see Sect. 3.5).
• Retrieve metadata about the OSS application (see Sect. 3.6).
• Carry out tasks not amenable to a simple read-update model (see Sect. 3.7).
3.2 OSS Façade Pattern 37
Example
As an example of the OSS Façade pattern, we will develop façades to support the
Simple Inventory OSS application (see Sect. 2.8) for each of the profiles using
JEE[2] and JMS[6].
Fig. 3.4 OSS Session Facade Implemented in JEE
In our session profile example, the façade is implemented by means of the EJB 3.0
session bean and the remote operations are implemented by RMI (see Fig. 3.4). The
interface declaration for the session bean would look like this:
/**
* Simple Inventory session bean declaration.
*
* This interface defines the operational aspects of the Simple
* Inventory session bean that implements the facade pattern.
*/
@Remote
public interface SimpleInventorySession
{
public ManagedEntityValue makeManagedEntityValue(

String valueType) throws ApplicationException;
public InventoryRecordValue getInventoryRecordByKey(

RecordKey key, String[] attrNames)
public InventoryRecordValueIterator getInventoryRecordsByTemplate(

InventoryRecordValue template,
String[] attributeNames) throws ApplicationException;
public void setInventoryRecordByValue(

InventoryRecordValue value, boolean resyncRequired)
public void setInventoryRecordsByValues(InventoryRecordValue[] recordvos)

public RecordKey createInventoryRecordByValue(

InventoryRecordValue value)
public void removeInventoryRecordByKey(RecordKey key)

public String[] getManagedEntityTypes()

public NamedProcedureRequest makeNamedProcedureRequest(

public NamedProcedureResponse execute(NamedProcedureRequest namedProcedure)

}
In EJB 3.0, the session bean is declared as plain Java interface but with the anno-
tation @Remote to denote a remote interface. We will describe the remote methods
in the following sections:
makeInventoryRecordValue() make an inventory record value-object given
the name of the inventory record value-type (see Sect. 4.2).
getInventoryRecordByKey() return, in a value object, the requested at-
tribute values of the inventory record managed-entity indicated by the supplied key
(see Sect. 4.3).
getInventoryRecordsByTemplate() return an iterator (see Sect. 3.4) that
will return, in value objects, the requested attribute values of the inventory record
managed-entities matching the supplied template (see Sect. 4.5).
setInventoryRecordByValue() update the attribute values of an inventory
record managed-entity using the fields in the supplied value object (see Sect. 4.3).
setInventoryRecordsByValues() update the attribute values of multiple
inventory record managed-entities atomically using the fields in the supplied value
objects (see Sect. 4.6).
createInventoryRecordByValue() create an inventory record managed-
entity using the fields in the supplied value object (see Sect. 4.2).
removeInventoryRecordByKey() remove (delete) the inventory record managed-
entity indicated by the supplied key (see Sect. 4.2).
getManagedEntityTypes() return an array of strings representing the fully-
qualified names of managed-entity types supported by the façade (see Sect. 3 .6 ).
makeNamedProcedureValue() return a empty named-procedure value-object
(see Sect. 3.7).
execute() return the results of a named-procedure call (see Sect. 3.7).
3.2 OSS Façade Pattern 39

In our message profile example, the façade is implemented by means of a Java Mes-
sage Service (JMS)[6] queue and a message-driven bean (see Fig. 3.5). The client
enqueues a JMS message containing the request document onto the message queue
from where it is removed by the message-driven bean. The bean parses the mes-
sage and makes the appropriate call on the OSS application. The message-driven
bean encodes the reply or exception it receives from the OSS application into a JMS
message, and places it on a message queue for return to the client application.
Fig. 3.5 OSS Message Façade Implemented In JMS
To illustrate the use of the OSS Façade pattern in the message profile, we will
define schema fragments for the two operations getInventoryRecordByKey and
setInventoryRecordByValue. The following schema fragment defines the get-
InventoryRecordByKey request and response types and elements:

<complexType name="GetInventoryRecordByKeyRequestType">
<sequence>
<element name="recordKey" type="entities:RecordKeyType"/>
<element name="attributeNames" type="appmsg:ArrayOfString" minOccurs="0"/>
</sequence>
</complexType>
<complexType name="GetInventoryRecordByKeyResponseType">
<sequence>
<element name="record" type="entities:InventoryRecordValueType"/>
</sequence>
</complexType>

<element name="getInventoryRecordByKeyRequest"
type="appmsg:GetInventoryRecordByKeyRequestType"/>
<element name="getInventoryRecordByKeyResponse"
type="appmsg:GetInventoryRecordByKeyResponseType"/>
The following schema fragment defines the setInventoryRecordByValue re-

quest and response types and elements:

<complexType name="SetInventoryRecordByValueRequestType">
<sequence>
</sequence>
</complexType>
<complexType name="SetInventoryRecordByValueResponseType">
<sequence/>
</complexType>

<element name="setInventoryRecordByValueRequest"
type="appmsg:SetInventoryRecordByValueRequestType"/>
<element name="setInventoryRecordByValueResponse"
type="appmsg:SetInventoryRecordByValueResponseType"/>
<element name="setInventoryRecordByValueRequestException"
type="appmsg:ApplicationFaultType"/>
The following schema fragment defines the ApplicationFaultType type and ele-
ment:

<complexType name="ApplicationFaultType">
<sequence>
<element name="errorMessage" type="string"/>
</sequence>
</complexType>
The full schema is given in Appendix A.
Summary
The OSS Façade pattern encourages the definition of a consistent set of operations
to be exposed by all OSS applications. By defining such a set, the learning curve as-
sociated with integrating a number of OSS applications into a management solution
will be reduced.
3.3 OSS Event Notification Pattern 41
3.3 OSS Event Notification Pattern
In modern telecommunications systems, the performance of transmission and switch-

ing equipment is closely monitored by OSS applications to ensure service quality.
OSS applications monitor equipment for asynchronous events such as equipment
malfunctions, call completions, time-outs, completion of statistics-gathering peri-
ods, and transmission degradation. An OSS application will monitor equipment
either by polling it on a periodic basis or by waiting for the equipment to notify
the application. Notifications that indicate equipment malfunction are referred to
as alarms. OSS applications also monitor events in business systems, such as or-
der management systems, to determine progress. A CRM application can deter-
mine the progress of a transaction by monitoring the various task-completion events
(see Sect. 3.8). OSS application will normally process the information accompany-
ing event notifications, for example, to correlate alarms or accumulate longer-term
statistics, and then make the information available to multiple OSS clients asyn-
chronously.
Fig. 3.6 OSS Event Notification Service
Intent
Provide a resilient mechanism to permit OSS applications to asynchronously notify

OSS clients of event occurrences.
Motivation
OSS applications need to notify multiple OSS clients about event occurrences at
unpredictable times, and OSS clients need to be able to select the types of events
about which they are prepared to receive information and the rate at which they are
prepared to receive it.
Solution
Use a publish-and-subscribe model for event notification. An OSS application pub-

lishes its event notifications to a notification service (which acts somewhat like a
bulletin board), and clients subscribe to receive certain types of event notifications
when they are posted to the notification service. The arrangement is show in Fig. 3.6.
In order to receive messages, an OSS client will:
1. Subscribe to the particular notification service possibly specifying a selector that
requests the notification-service provider to filter notifications sent.
2. Wait for a notification to arrive.
3. Process the notification when it arrives.
The sequence is illustrated in Fig. 3.7.
Fig. 3.7 Use of OSS Event Notification Pattern
Example

In this OSS Session Profile example, we will use the Java Message Service (JMS)[6]
to implement the OSS Event Notification pattern. The JMS message will be of type
ObjectMessage—a serializable Java object. In the following example code, we will

illustrate how an event, the creation of an inventory record managed-entity, notified
by the Simple Inventory application, might be handled by a Java client.
We first define the BaseEvent and RecordCreateEvent interfaces that will give
access to the payload of the message:
/**
* Base interface to access the payload of all Simple
* Inventory event notification messages
*/
public interface BaseEvent extends java.io.Serializable {
/*
* Accessor for the time the event was published as a String
*/
public String getEventTimeAsString();
/*
* Accessor for the time the event was published
*/
public Calendar getEventTime()
}
/**
* Interface to access the payload
* of the record-create notification
*/
public interface RecordCreateEvent extends BaseEvent {
/*
* Accessor/mutator for the record created
*/
public InventoryRecordValue getInventoryRecordValue()
public void setInventoryRecordValue(InventoryRecordValue value)

}
We next implement the MessageListener interface and the onMessage() method;

the onMessage() method is called when a message arrives at the client. The method
verifies that the message is a notification of the creation of an inventory record
managed-entity, extracts the contents, and prints the content details.
/**
* Implementation of the onMessage method to handle
* receiving a record-creation event notification
*
*/
public class OSSListenerImplementation implements
javax.jms.MessageListener {
public void onMessage(Message message) {

System.out.println("\nMessage Received--->");
ObjectMessage eventMessage = null;

Object eventMessageContent;
BaseEvent event;
if (message != null) {
if (message instanceof ObjectMessage) {
try {
eventMessage = (ObjectMessage) message;
eventMessageContent = eventMessage.getObject();
if (eventMessageContent instanceof BaseEvent) {
event = (BaseEvent) eventMessageContent;
if (event instanceof RecordCreateEvent) {
RecordCreateEvent rce = (RecordCreateEvent) event;
System.out.println("Message type: RecordCreateEvent notification");
System.out.println("Event Time= " + event.getEventTimeAsString());
System.out.println("Notification content: " +
"\n" + rce.getInventoryRecordValue().toString());
}
if (event instanceof RestoreFromBackUpStateEvent) {
RestoreFromBackUpStateEvent rce = (RestoreFromBackUpStateEvent) event;

System.out.println(
"Message type: RestoreFromBackUpStateEvent notification");
System.out.println("Event Time= " + rce.getEventTimeAsString());
System.out.println("Notification content: Restore status=" + rce.
getState() + " Completion=" + rce.getCompletionMeter() + "%");
}
}
} catch (ApplicationException ex) {
Logger.getLogger(InventoryEventMain.class.getName()).log(Level.SEVERE,
null, ex);
} catch (JMSException ex) {
Logger.getLogger(InventoryEventMain.class.getName()).log(Level.SEVERE,
null, ex);
}
} else {
System.out.println("Received invalid event: " +
message.toString());
}
}
}
}
Finally, we run the following code, to register the OSS client to receive messages:
/*
* Register the MessageListener and start message delivery
*/
String destName = null;
String topicFactory = null;
InputStreamReader inputStreamReader;
char answer = 0;
try {
Context jndiContext = null;
ConnectionFactory connectionFactory = null;
Connection connection = null;
Session session = null;
Destination dest = null;
MessageConsumer consumer = null;
destName = "jms/simpleInventoryTopic";
topicFactory = "jms/simpleInventoryTopicFactory";
/*
* Create a JNDI InitialContext object if none exists

*
*/
try {
jndiContext = new InitialContext();
} catch (NamingException e) {
System.out.println("Could not create JNDI API context: " + e.toString());
System.exit(1);
}
/*
* look-up connection factory and destination.
*/
try {
connectionFactory = (ConnectionFactory) jndiContext.lookup(
topicFactory);
dest = (Destination) jndiContext.lookup(destName);
} catch (Exception e) {
System.out.println("JNDI API lookup failed: " + e.toString());
System.exit(1);
}
/*
* Create the connection.
*/
connection = connectionFactory.createConnection();
session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
consumer = session.createConsumer(dest);
MessageListener listener = new OSSListenerImplementation();
/*
* Register the listener and start delivery
*/
consumer.setMessageListener(listener);
connection.start();
The report of the creation of an equipment record managed-entity will look like
this:
Message Received--->
Message type: RecordCreateEvent notification
Event Time= 2009 3 3 1h37 50s
Notification content:

RecordId = 42
RecordType = EquipmentRecordType
RecordCreationDate = 2009 3 3 1h37 49s
NumberOnHand = 10
Location = Montreal

In this OSS Message Profile example, we will again use the Java Message Service
(JMS) to implement the OSS Event Notification pattern. The JMS message will be
of type TextMessage—a text message that contains an event-notification document.
The following schema fragment defines the base notification type and the create-
record notification type and element.

<xsd:complexType name="BaseEventNotifcationType">
<xsd:sequence>
<xsd:element name="eventTime" type="xsd:date" nillable="false"/>
</xsd:sequence>
</xsd:complexType>

<xsd:complexType name="RecordCreateEventType">
<xsd:complexContent>
<xsd:extension base="appmsg:BaseEventNotifcationType">
<xsd:sequence>
<xsd:element name="inventoryRecordValue"
type="entities:InventoryRecordValueType"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>

<xsd:element name="recordCreateEventNotification"
type="appmsg:RecordCreateEventType"/>
The notification payload for the creation of an equipment record managed-entity

might look like this:

<appmsg:recordCreateEventNotification
xmlns:appmsg=’http://xml.netbeans.org/schema/appmsg’
http://xml.netbeans.org/schema/appmsg file:...
<appmsg:eventTime>2009-02-20T13:20:00-05:00</appmsg:eventTime>
<appmsg:inventoryRecordValue xsi:type = "entities:EquipmentRecordValueType">
</appmsg:inventoryRecordValue>
</appmsg:recordCreateEventNotification>
Although the schema for the inventory-record create notification specifies the re-
turn of details of an inventory record, the xsi:type attribute indicates that details of
an extension of an inventory record, in fact an equipment record, have been returned.
Summary
Being able to flexibly handle the notification of asynchronous events is an impor-

tant requirement of managing telecommunications systems. Because multiple OSS
clients will want to selectively receive notifications from a number of OSS applica-
tions, a publish-and-subscribe model, using a message-based notification service, is
preferred.
3.4 OSS Iterator Pattern
From a software engineering perspective (for example memory-allocation or band-

width considerations), there will always be a limit to the amount of data that an OSS
client can accommodate in one response. An OSS client therefore needs a consistent
way to manage the flow of data that it receives from an OSS application in response
to a request that it has made.
Intent
Provide a mechanism to permit OSS clients to receive an undetermined amount of

data piecemeal.
Motivation
Some OSS requests, such as query requests and template matching requests, can
potentially match a large number of managed entities. The OSS client cannot deter-
mine how many managed entities are going to be matched and how many managed-
entity values or keys might subsequently be returned. If all of the data were to be
returned in one response, it might overwhelm the OSS client.
Solution
Rather than returning all of the managed-entity values or managed-entity keys cor-
responding to a template or query request in a single response, return an iterator
from which the OSS client can iteratively request a small number of values or keys
for processing. Fig. 3.8 shows how the OSS Iterator pattern is used in the case of
a query potentially returning a large number of managed-entity values. The OSS
client prepares a query, sends it to the OSS application, and receives an iterator in
response. The client then requests the next “n” managed-entity values, receives at
most “n” managed-entity values from the iterator, and extracts the required attribute
values. This process is continued until the OSS client receives an empty return indi-
cating the end of the sequence. The OSS client then deletes the iterator.
Being able to abandon the iteration part way through when, for example, the
required values or keys have been returned, is an added benefit. The OSS Iterator
pattern is based on the Iterator pattern[5].
In the OSS Session Profile, the iterator is implemented as an object with method
getNext<items>(n); in the OSS Message Profile, the iterator is implemented by
including in the request and response documents additional complex types to allow
for multiple responses. We will look at these implementations in more detail in the
next section.
3.4 OSS Iterator Pattern 49
Fig. 3.8 Use of OSS Iterator Pattern
Example
To illustrate the use of the OSS Iterator pattern, we will use it, in the Simple Inven-
tory application, to print a list of all of the equipment items and numbers on hand in
Montreal.

In the following Java example, the iterator is implemented as a serializable Java
object with a method getNext<items>(n) to return the next n items. Here is how
we might use it:
/*
* Managed-entity value iterator/ template pattern example
*
* Return all equipment items and numbers-on-hand in Montreal
*/
SimpleInventorySession session;
EquipmentRecordValue template, equipvo;
InventoryRecordValue recordvos[];
InventoryRecordValueIterator iterator;
/*
* Get Simple Inventory session bean
*/
ServiceLocator serviceLocator = new ServiceLocator();
session = serviceLocator.getInventorySession();
/*
* Make an equipment record value object to use as a template
*/
template = (EquipmentRecordValue) session.makeManagedEntityValue(
"simpleinventory.EquipmentRecordValue");
/*
* Set the location field in the template
*/
template.setLocation("Montreal");
/*
* Request all equipment records where location = "Montreal"
*/
iterator =
session.getInventoryRecordsByTemplate(template, null);
/*
* Process 5 equipment record-value objects at a time
*/
recordvos = iterator.getNextInventoryRecords(5);
while (recordvos.length > 0) {
for (int i = 0; i < recordvos.length; i++) {
equipvo = (EquipmentRecordValue) recordvos[i];
System.out.println(equipvo.getEquipmentType() + " " +
String.valueOf(equipvo.getNumberOnHand()));
}
recordvos =
iterator.getNextInventoryRecords(5);
}
iterator.remove();
In the above code snippet, the OSS client:

• Obtains a reference to a Simple Inventory session bean.
• Requests the session bean make and return an equipment record value-object to
use as a template, and then populates the location field with the string “Montreal”.
• Executes the getInventoryRecordsByTemplate() operation (see Sect. 4.5) on
the session bean with the value object as the parameter, and receives an iterator
object in return.
• Repeatedly requests, from the iterator object, an array of 5 equipment record
value-objects at a time and prints the required fields.
• Deletes the iterator.
The client code above executes a getInventoryRecordsByTemplate() request
but, because the parameter (i.e the template) is of type EquipmentRecordValue,
the operation will only match equipment records. We discuss this in more detail in
Sect. 4.5.
3.4 OSS Iterator Pattern 51

In order to implement the OSS Iterator pattern in the OSS Message Profile exam-
ple, we define two additional complex types, IteratorRequest and IteratorRe-
sponse, as follows:

<complexType name="IteratorRequest" abstract="false">
<sequence>
<element name="n" type="unsignedInt" nillable="true" minOccurs="0"/>
</sequence>
</complexType>
<complexType name="IteratorResponse" abstract="false">

<sequence>
<element name="sequence" type="int"/>
<element name="endOfReply" type="boolean"/>
</sequence>
</complexType>
The IteratorRequest complex type defined in the above schema fragment in-
cludes the element, <n>, to indicate the maximum number of value documents to be
returned in the response. The IteratorResponse complex type definition includes
two additional elements: <sequence>, an ordinal indicating the ordering of the re-
sponse, and <endOfReply>, a boolean indicating the last response of the sequence.
These complex types are introduced into simple request and response documents by
means of the XML Schema element <extension>.
The schema fragment for the getInventoryRecordsByTemplateRequest and
getInventoryRecordsByTemplateResponse types is as follows:

<complexType name="GetInventoryRecordsByTemplateRequestType">
<complexContent>
<extension base="appmsg:IteratorRequest">
<sequence>
<element name="template" type="entities:InventoryRecordValueType"/>
<element name="attrNames" type="appmsg:ArrayOfString" minOccurs="0"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="GetInventoryRecordsByTemplateResponseType">
<complexContent>
<extension base="appmsg:IteratorResponse">
<sequence>
<element name="records" type="entities:InventoryRecordValueType"
maxOccurs="unbounded"/>
</sequence>
</extension>
</complexContent>
</complexType>

<element name="getInventoryRecordsByTemplateRequest"
type="appmsg:GetInventoryRecordsByTemplateRequestType"/>
<element name="getInventoryRecordsByTemplateResponse"
type="appmsg:GetInventoryRecordsByTemplateResponseType"/>
<element name="getInventoryRecordsByTemplateResponseException"
To illustrate the use of the OSS Iterator pattern in the message profile, we will
use the same example as in session profile example—making a list of all the equip-
ment items on hand in Montreal. The following XML document requests equipment
record value-documents, two at a time, for all equipment records where location
is “Montreal”. The <appmsg:template> element type in the document is derived
from the type defined by the schema fragment (i.e. InventoryRecordValueType)
by use of the xsi:type attribute indicating that equipment records and extended
equipment records are to be matched.

<appmsg:getInventoryRecordsByTemplateRequest
<appmsg:n>2</appmsg:n>
<appmsg:template xsi:type = "entities:EquipmentRecordValueType">
</appmsg:template>
</appmsg:getInventoryRecordsByTemplateRequest>
Summary
The OSS Iterator pattern is an important pattern for the practical implementation
of OSS integration interfaces: it allows OSS clients to control the rate at which
information is returned from OSS applications.
3.5 OSS Factory Pattern 53
3.5 OSS Factory Pattern
A number of OSS patterns are realized by the passing of value types (managed-
entity values, managed-entity keys, or named-procedure values) between OSS clients
and OSS applications; examples include the Managed-Entity Life Cycle pattern (see
Sect. 4.2) and the OSS Named-procedure pattern (see Sect. 3.7). In a typical sce-
nario an OSS client will:
• make an instance of the particular value type;
• populate the fields of the instance as required; and
• transfer the instance to the OSS application for it to execute the pattern.
In order for an OSS client to be able to make an instance of a value type, it would
normally need to have access to a local copy of the related specification. During the
life cycle of an OSS application, the specifications and implementations of value
types may change to accommodate upgrades or patches, and having to distribute
revised specifications to OSS clients in a timely manner would be a maintenance
headache. The solution is to put the responsibility on the OSS client to make or
obtain up-to-date instances of value types.
Fig. 3.9 OSS Factory Pattern—Instance Creation
Intent
Enable OSS clients to make or obtain up-to-date instances of value types without
local knowledge of the related specification.
Motivation
The primary motivation of the OSS Factory pattern is to reduce the level of coupling
between an OSS client and an OSS application. For example, if an OSS application
were to be upgraded or vendors were to make extensions that changed the imple-
mentation of value type, each OSS client would have to be updated and possibly
re-compiled to take advantage of the upgrades or extensions. In a large telecommu-
nications system, it would be a substantial logistical problem.
Solution
In our experience there are two useful approaches, either:

• provide a factory that exposes methods to make instances of value types and
metadata about the value types supported by the factory (see Fig. 3.9); or
• provide a repository that makes available specifications of value types and meta-
data about the value types supported by the repository (see Fig. 3.10).
Fig. 3.10 OSS Factory Pattern—Schema Retrieval
In the OSS Session Profile, OSS clients obtain object implementations from fac-
tories. The OSS Session Façade and managed-entity value-objects are factories
for managed-entity value instances and managed-entity key instances respectively.
Types and keys are arranged in type hierarchies to support polymorphic operations.
In the OSS Message Profile, OSS clients obtain document specifications, in the form
of XML schemata, from external repositories. The XML Schema types are arranged
in a derivation hierarchy (i.e. by using the extension element in XML Schema), to
support polymorphic operations.
Example
In the following example, we will show how a Java client might request the man-
ufacture of a record key and use it to get a particular Simple Inventory equipment
record value-object.
/*
* Factory pattern example--make and use a key
*/
EquipmentRecordValue recordvo;
RecordKey key;
/*
*/
/*
* The Simple Inventory session bean is a factory
* for creating Inventory Record value-objects...
*/
recordvo = (EquipmentRecordValue) session.makeManagedEntityValue(
/* ...and the Inventory Record value-object is a factory for making

* record keys
*/
key = recordvo.makeRecordKey();
/*
* The key is empty, so populate it
*/
key.setRecordId("42");
key.setRecordType("EquipmentRecordType");
/*
* Try the key
*/
null);
The OSS client first gets a reference to a Simple Inventory session bean. It next
requests the session bean to make an equipment record value-object, and then uses
it to make a record key. The OSS client then populates the key, and requests an
equipment record value-object corresponding to the key. Running the above code
might result in the following output:

Record Id = 42
NumberOnHand = 10
Location = Montreal

We saw in Sect. 3.1 that instances of documents in the OSS Message Profile serve
the same purpose as Java value objects in the OSS Session Profile. An OSS client
makes an instance of a document locally using the appropriate schema, and pop-
ulates the document as required. This approach requires that the relevant schema
be available to the OSS client. Rather than each client maintaining copies of the
relevant schemata, they are stored in, and obtained from, registries. Registries that
store and make available XML schemata include those defined by UDDI[7] and
ebXML[8].
The following is the XML Schema for the <GetInventoryRecordByKeyRe-
quest> and <GetInventoryRecordByKeyRequest> elements for the Simple In-
ventory:

<sequence>
</sequence>
</complexType>
<sequence>
</sequence>
</complexType>

A client might populate the key in the request document as shown below:

<appmsg:getInventoryRecordByKeyRequest
xsi:schemaLocation=’http://xml.netbeans.org/schema/appmsg file:...
http://xml.netbeans.org/schema/Entities file:...
<appmsg:recordKey>
</appmsg:recordKey>
</appmsg:getInventoryRecordByKeyRequest>
And the response might look like this:

<appmsg:getInventoryRecordByKeyResponse
<appmsg:record xsi:type = "entities:EquipmentRecordValueType">
</appmsg:record>
</appmsg:getInventoryRecordByKeyResponse>
Summary
The OSS Factory pattern centralizes either the definition of, or the implementation
of, value objects and documents thus reducing administrative issues associated with
application upgrades and vendor-specific extensions. By arranging the definitions in
a type hierarchy, polymorphic operations can be supported.
3.6 OSS Discovery Pattern

Reliability of the software that manages telecommunications services is of great im-
portance because of the critical nature of telecommunications. Type safety is an im-
portant aspect of the design of reliable software and, for that reason, OSS client im-
plementations are normally strongly typed. However, strong typing of OSS clients
makes it difficult for them to take advantage of newer, or vendor-enhanced, OSS
applications without some sort of modification. We need to provide a mechanism to
allow operators to take advantage of updated or vendor-enhanced OSS applications
without the need to modify and re-build the OSS client.
Intent
Provide OSS clients with a mechanism to dynamically discover the functionality of

OSS applications.
Motivation
As we have noted, type safety is an important part of software design. One of the
ways of achieving type safety is to make interfaces strongly typed, and to imple-
ment them using statically-typed programming languages such as Java or statically-
typed schemata, such as at XML Schema[3]. Static typing allows type errors to be
detected at compile time or at XML document generation time. However, statically-
typed interfaces and schemata imply a tight coupling between OSS client and OSS
application. To take advantage of upgraded or vendor-enhanced OSS applications,
statically-typed OSS clients have to be modified, and that can lead to a prolifera-
tion of versions of OSS clients. We need to provide a mechanism for OSS clients to
discover and use the functionality of an OSS application at runtime.
Solution
Require OSS applications and managed-entity values to expose metadata about the
functionality they offer. Using this metadata, an OSS client can dynamically build
a request (see Fig. 3.11) or process the results from a request (see example sec-
tion below). For example, a vendor-enhanced trouble-ticket managed-entity value
might expose metadata about additional fields in a trouble ticket; a generic operator-
support application can present those additional fields to the operator. Or an OSS
application might expose metadata to enable an operator to discover, and subscribe
to, event types supported by an OSS application. Metadata about the following is
typically useful:
• operations supported;
• attribute names supported;
• managed-entity types supported;
• named-procedure and query types supported;
• attributes of managed-entity types supported; and
• event types supported.
3.6 OSS Discovery Pattern 59
Discovering functionality at runtime can compromise type safety, and a software

designer needs to carefully strike a balance between, on the one hand, type-safety
and performance, and on the other, flexibility.
Fig. 3.11 Use of the OSS Discovery Pattern
Example
In the following examples, we will illustrate the use of the OSS Discovery pattern
to develop generic browsers to allow clients to browse the names of the managed
entities exposed by the session and message façades and the names and types of
their attributes.

Since the implementation of managed-entities is hidden, the client must discover
the information about managed entities from the managed-entity value interface in
the session profile. In the following code, the client first gets a reference to a Simple
Inventory session bean, and then discovers, from it, the names of the managed-entity
types—in this case, the names of the inventory record managed-entity types.
For each inventory record managed-entity type, the client requests the creation
of an inventory record managed-entity value-object and, from each, discovers the
names of the respective managed-entity attributes. By introspecting the accessors
of the field names of each managed-entity value, the client discovers the respec-
tive field types and hence can infer the types of the corresponding managed-entity
attributes.
/**
* Example of OSS Discovery pattern use: a generic managed entity browser
*/
ManagedEntityValue ir1;
String[] entityTypes;
/*
* Get the session bean
*/
/*
* Discover the names of the Simple Inventory managed-entity types
*/
try {
entityTypes = session.getManagedEntityTypes();
/*
* For Simple Inventory managed-entity type, request the
* session bean to make a inventory record value-type
*/
for (int i = 0; i < entityTypes.length; i++) {
ir1 = session.makeManagedEntityValue(entityTypes[i]);
System.out.println("Managed-entity value-type: " + entityTypes[i]);
/*
* Discover the names of the attributes of the inventory managed-entity
*/
String[] attributeNames = ir1.getAttributeNames();
/*
* For each attribute get the type by introspection
*/
for (int k = 0; k < attributeNames.length; k++) {
try {
String name = attributeNames[k];
String upperCaseString = name.substring(0, 1).toUpperCase() + name.
substring(1);
Method method = ir1.getClass().getMethod("get" + upperCaseString);

System.out.println("\tAttribute name: " + attributeNames[k] + " (" +
method.getReturnType().getName() + ")");
} catch (NoSuchMethodException ex) {

Logger.getLogger(MainTest.class.getName()).log(Level.SEVERE, null, ex);
} catch (SecurityException ex) {
Logger.getLogger(MainTest.class.getName()).log(Level.SEVERE, null, ex);
}
}
System.out.println("----------------------------------------------");
}
} catch (ApplicationException e) {
System.out.println("Error encountered:" + e.getMessage());
System.exit(-1);
}
The output of browsing the Simple Inventory façade will look like this:
Managed-entity value-type: ManagedEntityValue

Attribute name: RecordKey (simpleinventory.RecordKey)
Attribute name: LastUpdateVersionNumber (long)
----------------------------------------------
Managed-entity value-type: simpleinventory.InventoryRecordValue
Attribute name: RecordCreationDate (java.util.Calendar)
----------------------------------------------
Managed-entity value-type: simpleinventory.EquipmentRecordValue
Attribute name: RecordCreationDate (java.util.Calendar)
Attribute name: EquipmentType (java.lang.String)
Attribute name: NumberOnHand (int)
Attribute name: Location (java.lang.String)
----------------------------------------------
...

As for the session profile, we will illustrate the OSS Discovery pattern by develop-
ing a generic managed-entity browser to browse the names of the managed entities
exposed by the message façade and the names and types of their attributes. Since the
client does not know the implementation of the managed-entities, it must discover
the information about the managed entities from the façade XML schema.
In the code fragment below, the client first gets a reference to the schema and then
parses the schema to build a list of global element specifications that corresponds to
the managed-entity types. The client then iterates over the global element specifica-
tions to discover each of the names and types (these correspond to the names and
types of the managed entities exposed by the façade), and iterates over each of the
child element types to discover the names and types (these correspond to the names
and types of the attributes of the managed entities).
/**
* Example of OSS Discovery pattern use: a generic schema browser
*/
SchemaGlobalElement element;
//schemaFile = ... set location of schema file

File schema = new File(schemaFile);
SchemaTypeSystem schemaTypeSystem = null;
/*
* Parse the schema into a list of global element specifications
*/
schemaTypeSystem = XmlBeans.compileXsd(new XmlObject[]{
org.apache.xmlbeans.XmlObject.Factory.parse(schema)}, XmlBeans.
getBuiltinTypeSystem(), null);
SchemaGlobalElement[] elements = schemaTypeSystem.globalElements();
List list = Arrays.asList(elements);
/*
* Iterate over the list get the global element names and types
*/
for (Iterator iterator = list.iterator(); iterator.hasNext();) {
element = (SchemaGlobalElement) iterator.next();
System.out.println("Element Name: " +
element.getName().getLocalPart());
System.out.println("Element Type: " + element.getType());
/*
* Print out the child elements--the attribute names and types
*/
printElementChildren(element);
}
}
/**
* Print out the names and types of child elements of input element
*
*/
public void printElementChildren(SchemaGlobalElement element) {
SchemaType xyz = element.getType();

SchemaParticle toto = xyz.getContentModel();
SchemaParticle[] atts = null;
if (toto != null) {
if (toto.getParticleType() == SchemaParticle.SEQUENCE) {
atts = toto.getParticleChildren();
}
if (atts != null) {
for (int kk = 0; kk < atts.length; kk++) {
System.out.println("Attribute Name " + atts[kk].getName());
System.out.println("Attribute Type " + atts[kk].getType().getName());
if (atts[kk].getParticleType() == SchemaParticle.ELEMENT) {
SchemaLocalElement zzz = (SchemaLocalElement) atts[kk];
}
}
}
}
System.out.println("-----------------------------------------------------");
}
The output of browsing the Simple Inventory façade schema will look like this:
Element Name: inventoryRecordKey

Element Type: T=RecordKeyType@http://xml.netbeans.org/schema/Entities
Attribute Name {http://xml.netbeans.org/schema/Entities}recordId
Attribute Type {http://www.w3.org/2001/XMLSchema}string
Attribute Name {http://xml.netbeans.org/schema/Entities}recordType
-----------------------------------------------------
Element Name: managedEntityValue
Element Type: T=ManagedEntityValueType@http://xml.netbeans.org/schema/Entities
Attribute Name {http://xml.netbeans.org/schema/Entities}recordKey
Attribute Type {http://xml.netbeans.org/schema/Entities}RecordKeyType
Attribute Name {http://xml.netbeans.org/schema/Entities}lastUpdateNumber
Attribute Type {http://www.w3.org/2001/XMLSchema}long
-----------------------------------------------------
Element Name: inventoryRecordValue
Element Type: T=InventoryRecordValueType@http://xml.netbeans.org/schema/Entities

Attribute Name {http://xml.netbeans.org/schema/Entities}creationDate
Attribute Type {http://www.w3.org/2001/XMLSchema}dateTime
-----------------------------------------------------
Element Name: equipmentRecordValue
Element Type: T=EquipmentRecordValueType@http://xml.netbeans.org/schema/Entities
Attribute Name {http://xml.netbeans.org/schema/Entities}creationDate
Attribute Type {http://www.w3.org/2001/XMLSchema}dateTime
Attribute Name {http://xml.netbeans.org/schema/Entities}equipmentType
Attribute Name {http://xml.netbeans.org/schema/Entities}numberOnHand
Attribute Type {http://www.w3.org/2001/XMLSchema}int
Attribute Name {http://xml.netbeans.org/schema/Entities}location
-----------------------------------------------------
...
Summary
The OSS Discovery pattern allows developers to strike a balance between type
safety and future proofing in the design of interfaces to OSS applications.
3.7 OSS Named-Procedure Pattern
During the life cycle of an OSS application, new operations and queries may need
to be added to extend functionality and accommodate vendor-specific extensions.
In addition, not all of the day-to-day tasks of network managers can be supported
by OSS clients that implement patterns such as the Managed-Entity Update pat-
tern (see Sect. 4.3) or the Managed-Entity Template Filter pattern (see Sect. 4.5).
A number of routine, but important, tasks may be quite complex and may be the
subject of complex business or consistency rules that evolve over time. Other tasks
might be complex, but routine, queries that are not amenable to associative look-up
techniques.
Intent
To provide a flexible and extensible method for defining arbitrary procedures and
queries.
Motivation
It is not usual to be able to predict all of the operations that are needed during the
design of an OSS application; it is often necessary to add operations as applications
mature and new requirements are identified. If new operations were to be added to
the façade, it would lead to a proliferation of operations and require the repeated
re-compilation and redeployment of clients to take advantage of the new features.
In addition, relying on OSS clients to correctly validate operator input to com-
plex procedures invoked on OSS applications adds complexity to the OSS clients
and is risky from an operational perspective. Allowing operators to invoke complex
queries based on just associative lookup techniques can have consequences in terms
of performance and availability of OSS applications.
Solution
Use strongly-typed value types to carry the name and the parameters of named pro-
cedures to OSS applications and to return results. The general approach is for OSS
applications to define value types for the named procedures that OSS clients can ei-
ther obtain, or locally instantiate, and populate with the required parameters. When
an OSS application receives such a value instance, it can validate the parameters
and apply any business or consistency rules before carrying out the procedure. The
application returns any results as a value type. Fig. 3.12 illustrates the approach.
In addition to centralizing validation, the pattern centralizes the maintenance of
the business and consistency rules. It can also reduce network traffic by replacing a
3.7 OSS Named-Procedure Pattern 65
Fig. 3.12 Use of the OSS Named-procedure Pattern
number of simple operations with fewer, higher-value, operations. The pattern also
helps reduce complexity in OSS clients.
In collaboration with the OSS Discovery pattern (see Sect. 3.6) and the OSS Fac-
tory pattern (see Sect. 3.5), the pattern can help OSS clients accommodate updates
or vendor-specific extensions to OSS applications without modification. The pattern
is based on the Command pattern[9].
Example
Using the Simple Inventory application, suppose we want to routinely obtain a list
of all the equipment records, filtered by location, that have fallen below their re-
order level. Given only the Managed-Entity Template Filter pattern, we would have
to bring back to the client managed-entity values representing all of the equipment
records for the desired location and locally select those where the number-on-hand
had dropped below the re-order level—not a pretty solution. A better solution is to
do the filtering on the OSS and return only the relevant managed-entity values. We
will define a named procedure to do just that.

In the OSS Session Profile, and using Java, we first declare the base interfaces for
the Named-procedure request and response value objects:
/**
* Base interface for the named-procedure-request value-objects
*/
public interface NamedProcedureRequest extends java.io.Serializable {
}
/**
* Base interface for named-procedure response value-objects
*/
public interface NamedProcedureResponse extends java.io.Serializable{
}
We next extend the Named-procedure request interface to declare the Query-reorder-

items request interface, and extend Named-procedure response and the Inventory-
record value Iterator interfaces to declare the Query-reorder-items response inter-
face:
/**
* Query re-order-items request interface
*/
public interface QueryReorderItemsRequest extends NamedProcedureRequest {
public static final String LOCATION = "location";
/**
* mutator for the single parameter "location"
*/
void setLocation(String location);
}
/**
* Query re-order-items response interface
*/
public interface QueryReorderItemsResponse extends NamedProcedureResponse,
InventoryRecordValueIterator {
}
The following snippet of code requests a Query-reorder-items request value-object

from the session bean, populates with the value “Toronto”, and invokes the query on
the Simple Inventory application. The application responds with an iterator that can
be used to fetch the value objects corresponding to the extended equipment-records
where the items on-hand have fallen below the re-order level.
/*
* Named-procedure example
* Request list of equipment-levels by location that
* have fallen below the re-order level
*/
QueryReorderItemsRequest query;
InventoryRecordValue irvo;
/*
*/
//get a QueryReorderItemsValue object

query = (QueryReorderItemsRequest) session.makeNamedProcedureRequest(
"simpleinventory.QueryReorderItemsRequest");
//set the location field in the template

query.setLocation("Toronto");
iterator = (InventoryRecordValueIterator) session.execute(query);
//process 10 equipment record value-objects at a time

irvo = recordvos[i];
System.out.println(irvo.toString());
}
recordvos =
}
iterator.remove();
The output might look like this:

Equipment type = LineCard
Number on hand = 9
Location = Toronto
Reorder level = 10
Supplier Name = Nortel
Equipment type = PowerSupply
Number on hand = 25
Location = Toronto
Reorder level = 27
Supplier Name = Acme
...

As an example of the use of the OSS Named-procedure pattern in the message
profile, we will use the re-order example in the OSS Session Profile above, noting
that instances of documents in the OSS Message Profile serve the same purpose as
Java value objects in the OSS Session Profile (see Sect. 3.1). As an example, and
using XML Schema, we first define the base types, NamedProcedure request and
response types and elements.

<xsd:complexType name="NamedProcedureRequestType">
<xsd:sequence/>
</xsd:complexType>
<xsd:complexType name="NamedProcedureResponseType">
<xsd:sequence/>
</xsd:complexType>
<xsd:element name="namedProcedureRequest"
type="appmsg:NamedProcedureRequestType"/>
<xsd:element name="namedProcedureResponse"
type="appmsg:NamedProcedureResponseType"/>
We next extend the NamedProcedure request and response type specifications to

include the iterator request and response element definitions to allow the client
to control the flow of information returned from the OSS application.

<xsd:complexType name="IteratorNamedProcedureRequestType">
<xsd:extension base="appmsg:NamedProcedureRequestType">
<xsd:sequence>
<element name="iteratorRequest" type="appmsg:IteratorRequest"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexType>
<xsd:complexType name="IteratorNamedProcedureResponseType">
<xsd:extension base="appmsg:NamedProcedureResponseType">
<xsd:sequence>
<element name="iteratorResponse" type="appmsg:IteratorResponse"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexType>
<xsd:element name="iteratornamedProcedureRequest"
type="appmsg:IteratorNamedProcedureRequestType"/>
<xsd:element name="IteratorNamedProcedureResponse"
type="appmsg:IteratorNamedProcedureResponseType"/>
We next define the QueryReorderItems value and response types by extending

the respective IteratorNamedProcedure types to include the location element
definition and the records element definition respectively.

<xsd:complexType name="QueryReorderItemsRequestType">
<xsd:extension base="appmsg:IteratorNamedProcedureRequestType">
<xsd:sequence>
<xsd:element name="location" type="xsd:string"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexType>
<xsd:complexType name="QueryReorderItemsResponseType">
<xsd:extension base="appmsg:IteratorNamedProcedureResponseType">
<xsd:sequence>
<xsd:element name="records"
type="entities:ExtendedEquipmentRecordValueType"
</xsd:sequence>
</xsd:extension>
</xsd:complexType>
<xsd:element name="queryReorderItemsResponse"
type="appmsg:QueryReorderItemsResponseType"/>
<xsd:element name="queryReorderItemsRequest"
type="appmsg:QueryReorderItemsRequestType"/>
<xsd:element name="namedProcedureException"
Using the QueryReorderItems request schema, we next make an instance of

the query and populate the element <n> with the value 2 (that is requesting at most
two extended-equipment record value-documents be returned), and element <loca-
tion> with the value “Toronto”.

<appmsg:queryReorderItemsRequest
<appmsg:iteratorRequest>
</appmsg:iteratorRequest>
<appmsg:location>Toronto</appmsg:location>
</appmsg:queryReorderItemsRequest>
The first response might look like this:

<appmsg:queryReorderItemsResponse
<appmsg:iteratorResponse>
<appmsg:sequence>1</appmsg:sequence>
<appmsg:endOfReply>false</appmsg:endOfReply>
</appmsg:iteratorResponse>
<appmsg:records>
<entities:location>Toronto</entities:location>
<entities:reorderLevel>10</entities:reorderLevel>
<entities:supplierName>Nortel</entities:supplierName>
</appmsg:records>
<appmsg:records>
<entities:supplierName>Acme</entities:supplierName>
</appmsg:records>
</appmsg:queryReorderItemsResponse>
Summary
The Named-procedure pattern provides an extensible, but strongly-typed, method of

defining procedures or queries during the lifetime of an OSS application. It is based
on the Command pattern[9] and, like the Command pattern, the value type carries
the procedure name and the request parameters.
3.8 OSS Command–Status Pattern 71
3.8 OSS Command–Status Pattern
Some OSS management tasks involve multiple operations, and those operations in-
volving manual intervention may last for long periods of time, often measured in
days. For example, a Customer Relationship Management (CRM) application might
initiate the processing of a customer order. Customer orders for service can be long-
lived involving a number of operations, some of which might be assigned to OSS
applications such as work-order and configuration applications that involve manual
intervention. Rather that maintain the session with the client for the duration of the
transaction, the CRM application acknowledges the request and informs the client
of the progress of the request through a series of asynchronous notifications.
Fig. 3.13 Example of the Use of the OSS Command–Status Pattern
Intent
Minimize the amount of session information that an OSS client needs to retain in
order to complete long-lived requests.
Motivation
Some requests may take a long time to complete and requiring OSS clients to main-
tain session information about such requests can be impractical. However, the client
needs to know when a request has been completed and ideally the progress of the
request in the interim.
Solution
The OSS application sends periodic event notifications to inform the OSS client of
the progress of the request and when it has been completed.
Example
In the example shown in Fig. 3.13, we show how the Command–Status pattern might
be used for a long procedure, that of restoring the Simple Inventory database from
backup. The OSS client requests a named-procedure value-type to initiate a restore
of the Simple Inventory from backup, and sets the backup information field to re-
quest a full restore. The client then invokes the restore procedure, receives an ac-
knowledgment, and waits for notifications. As the restore procedure executes, the
client receives progress information in the form of event notifications.

The following code illustrates how the Command–Status pattern might be used in
the session profile. The client requests and populates a restore-from-backup-request
value-object from the session bean and populates it to request a full restore. It in-
vokes the restore-from-backup-request using the execute() operation on the ses-
sion bean, and exits waiting for event notifications using the onMessage() imple-
mentation shown in Sect. 3.3.
RestoreFromBackupRequest request;
RestoreFromBackupResponse response;
/*
*/
try {
/*
* Get a restore-from-backup Named-procedure value-object
* and set the backup information to "Full Restore"
*/
request = (RestoreFromBackupRequest) session.makeNamedProcedureRequest(
"simpleinventory.RestoreFromBackupRequest");
3.9 Summary 73
request.setBackupInfo("Full Restore");
/*
* Execute the name request and listen for notifications
*/
response = (RestoreFromBackupResponse) session.execute(request);
The client will receive a series of event notifications as follows:
Message type: RestoreFromBackUpStateEvent notification
Event Time= 2009 3 3 1h23 14s
Notification content: Restore status=STARTED Completion=0%
Event Time= 2009 3 3 2h26 19s
Notification content: Restore status=INPROGRES Completion=25%
Event Time= 2009 3 3 4h45 24s
Event Time= 2009 3 3 6h21 29s
Event Time= 2009 3 3 7h23 34s
Notification content: Restore status=COMPLETED Completion=100%
Summary
The OSS Command–Status pattern allows an OSS client to maintain minimal ses-
sion information in order to keep abreast of long-lived requests that it has made.
The OSS Event Notification Pattern is used to send asynchronous event notifica-
tions about progress and completion to the OSS client.
3.9 Summary
In this chapter, we have looked at a number of architectural patterns that we have

found useful in developing interfaces to OSS applications. Some patterns focus on
consistency, some on efficiency, and some balance the need for flexibility with the
need for safety. In the next chapter we will build on these patterns and look at a
number of useful programming patterns.
References
1. Data Transfer Object Pattern, Sun Developer Network,

http://java.sun.com/blueprints/corej2eepatterns/Patterns/TransferObject.html.
2. Java Platform, Enterprise Edition, Sun Developer Network, http://java.sun.com/javaee.
4. Façade Pattern, Sun Developer Network,
http://java.sun.com/blueprints/patterns/SessionFacade.html.
1994, pp. 257–271.
6. Java Message Service, Sun Developer Network, http://java.sun.com/products/jms.
7. Universal Description, Discovery, and Integration, http://uddi.xml.org.
8. Electronic Business using eXtensible Markup Language, http://www.ebxml.org/geninfo.htm.
1994, pp. 233–242.
Chapter 4
OSS Programming Patterns
To understand is to perceive patterns.

Isaiah Berlin
In the previous chapter we introduced a number of architectural patterns; in this

chapter we will use them as a foundation to introduce a number of programming
patterns. Two important patterns are the Managed-Entity Update pattern and the
Managed-Entity Life cycle pattern both of which support a CRUD (Create, Read,
Update, Delete) style of modification.
4.1 Managed-Entity Key Pattern
In managing telecommunications services, it is important to be able to unambigu-

ously reference a managed resource; for example, to be able to reference a particular
trouble ticket to update its status or to be able to reference a particular piece of com-
munications equipment to configure it.
Intent
Provide a mechanism to unambiguously refer to managed entities.
Motivation
In the OSS Managed-Entity Model (see Sect. 2.6), managed resources are modelled
as managed entities so, to refer to a managed resource, an OSS client must actually
refer to the managed entity that models the resource. (As we saw in Sect. 2.6, it
is the responsibility of the OSS application to maintain the relationship between
the managed resource and the managed entity.) Therefore to get an unambiguous
reference to a managed resource, we actually need to get an unambiguous reference
to a managed entity.
75
76 4 OSS Programming Patterns
Solution
All managed entities expose a key whose value is unique with respect to the other
managed entities within the application context. The application context is that nam-
ing context defined by an application that is responsible for the managed entities.
The Managed-Entity model does not prescribe the structure of the key nor the algo-
rithm used to determine equality of keys; the only requirement is that the value of
the key uniquely identify the managed entity within the application context.
When creating a managed entity, an OSS client can choose to assign the value of
the key or request that the OSS application assign the value of the key. In either case
it is the responsibility of the application to ensure the value of the key is unique.
In order for a client to create a key, the OSS application must make the structure
of the key available either by means of a factory method or by means of a schema.
Fig. 4.1 The Simple Inventory Key Model
Example
To illustrate the creation of keys, we will show how a client might obtain, popu-
late, and use a managed-entity key. The key structure of the Simple Inventory is, as
you might expect, fairly simple. It is two level structure: a naming context (Record
Type) and an identifier (ID) within that context, see Fig. 4.1.

In the following Java example using the OSS Session Profile, the OSS client first
gets a reference to a Simple Inventory session bean. It next requests the session
bean to make an equipment record value-object, and then uses it to create a record
4.1 Managed-Entity Key Pattern 77
key. The OSS client then populates the key, and requests an equipment record value-
object corresponding to the key.
/*
* Managed-entity Key Pattern Example--make a record key
*/
RecordKey key;
/*
*/
/*
* The Simple Inventory session bean is a factory
* for creating inventory record value-objects...
*/
/* ...and the inventory record value-object is a factory for making

* record keys
*/
/*
* The key is empty, so populate it
*/
/*
* Try the key
*/
null);
Running the above code might result in the following output:

Record Id = 42
NumberOnHand = 10
Location = Montreal

To use a managed-entity key in the message profile, an OSS client would either
have the schema for the key available locally or would obtain it from an external
repository (see Sect. 3.5).
The following is the XML Schema for the <GetInventoryRecordByKeyRe-

quest> and <GetInventoryRecordByKeyResponse> elements for the Simple In-
ventory:

<sequence>
</sequence>
</complexType>
<sequence>
</sequence>
</complexType>

A client might populate the key in the request document as shown below:

<appmsg:recordKey>
</appmsg:recordKey>

4.1 Managed-Entity Key Pattern 79

</appmsg:record>
Summary
The Managed-Entity Key pattern is a flexible way to unambiguously refer to man-

aged entities within an application context and hence unambiguously refer to man-
aged resources. The key structure and key matching algorithm are the responsibility
of the OSS application; the key structure is made available to OSS clients by use of
the OSS Factory Pattern (see Sect. 3.5).
4.2 Managed-Entity Life Cycle Pattern
As part of managing telecommunications services, we need to be able to model

the life cycle of managed resources. Logical resources, such as inventory records,
are created and deleted, and physical resources, such as line cards are activated or
de-activated.
Intent
Provide a mechanism to model the life cycle of managed resources.
Motivation
Managed entities are a consistent way to model the management aspects of managed
resources whether those resources be logical resources or physical resources. We
need to be able to model the creation of logical resources, such as the creation of
a trouble ticket, and the activation of physical resources, such as the activation of
a line card. And, of course, we need to model the reverse: the deletion of a trouble
ticket and the deactivation of a line card. In the Managed-Entity model, we could
do this by respectively creating and deleting the managed entities that represent the
managed resources, but the OSS Reference Architecture (see Sect. 2.3) does not
prescribe the implementation of managed entities, and that leaves us in a bit of a
quandary.
Solution
Use the Managed-Entity Value pattern to create managed entities. A single managed
entity is created by populating a managed-entity value with the desired values for
the managed-entity attributes and sending the managed-entity value to the façade
as an argument to a create request (see Fig. 4.2). Attributes corresponding to fields
not populated in the managed-entity value are set to default values by the façade.
The successful creation of the managed entity indicates the successful creation or
activation of the managed resource.
A single managed entity is deleted by sending a suitably populated key as an
argument to a delete request. The successful deletion of the managed entity indicates
the successful deletion or de-activation of the managed resource.
So far, we have only talked about the creation and deletion of single managed en-
tities, but bulk creation and deletion operations are useful. For example, the creation
of multiple managed entities with the same attribute values, the creation of mul-
tiple managed entities with different attribute values, and the deletion of multiple
managed entities with the same attribute values (see Sect. 4.6).
4.2 Managed-Entity Life Cycle Pattern 81
Fig. 4.2 An Example Managed-Entity Life Cycle
Example
In the following examples, we will show how clients might create and delete an
equipment record managed-entity in the Simple Inventory.

In the session profile example below, the OSS client uses the OSS Factory pattern
to make an empty managed-entity value-object, populates it with the desired values,
and then requests the session bean to create the managed entity that, in turn, creates
the corresponding record in the inventory. The client then tests the key, and finally
deletes the managed-entity.
/*
* Equipment Record Life Cycle Example
*/
EquipmentRecordValue recordvo, recordvo2;
RecordKey key;
String[] meTypes;
/*
*/
/*
* Get managed entity types supported by the session bean
*/
meTypes = session.getManagedEntityTypes();
for (int i = 0; i < meTypes.length; i++) {
System.out.println("ME TYPE= " + meTypes[i]);
}
/*
* get an empty equipment record value-object
*/
meTypes[2]);
/*
* Set the attribute values in the value object
*/
recordvo.setEquipmentType("LineCard");
recordvo.setLocation("Montreal");
recordvo.setNumberOnHand(10);
/*
* Make an empty record key (the equipment record value-object
* is a factory record keys)
*/
/*
* Populate the key
*/
/*
* Insert the key in the recordvo
*/
recordvo.setRecordKey(key);
/*
* Create the equipment record managed-entity
*/
key = session.createInventoryRecordByValue(recordvo);
/*
* To validate the insertion of the record into the inventory,
* request a new equipment record value-object
* corresponding the returned key and print the values
*/
recordvo2 = (EquipmentRecordValue) session.getInventoryRecordByKey(key,
null);
System.out.println(recordvo2.toString());
/*
* Delete the record using the record key
*/
session.removeInventoryRecordByKey(key);
The sequence of steps in the above code is as follows:

1. Create a Simple Inventory session bean.
2. Use the session bean to find out the names of the managed entities supported by
the Simple Inventory.
3. Use the session bean as a factory to make an empty equipment record value-
object.1
4. Set the required attribute values in the equipment record value-object.
5. Use the equipment record value-object as a factory to create a record key and
populate the key.
6. Request the session bean to create the equipment record managed-entity with
the value-object as a parameter (the Simple Inventory application will create the
corresponding equipment record).
7. Request a new equipment record value-object corresponding to the key that was
returned and print the record values.
8. Delete the equipment record managed-entity using the key (the Simple Inventory
application will delete the corresponding equipment record).
Running the above code will result in the following output:
ME TYPE= ManagedEntityValue
ME TYPE= simpleinventory.InventoryRecordValue
ME TYPE= simpleinventory.EquipmentRecordValue
ME TYPE= simpleinventory.ExtendedEquipmentRecordValue
ME TYPE= simpleinventory.SupplierRecordValue

Record Id = 42
NumberOnHand = 10
Location = Montreal

In the following JMS example using the message profile, the OSS client obtains a
copy of the schema for the <CreateInventoryRecordByValue> request element,
creates an XML document conforming to the schema, populates it with the desired
values, and sends it to the façade message queue.
1 Although the makeInventoryRecordValue() method is declared to return an object of

type InventoryRecordValue, due to the inherent polymorphism of Java, the method is happy
to return a sub-type i.e. EquipmentRecordValue; however the client has to cast the return to
keep the compiler happy.
The schema fragments for the CreateInventoryRecordByValue request and

response types are as follows:

<complexType name="CreateInventoryRecordByValueRequestType">
<sequence>
</sequence>
</complexType>
<complexType name="CreateInventoryRecordByValueResponseType">
<sequence>
<element name="record" type="entities:RecordKeyType"/>
</sequence>
</complexType>

<element name="createInventoryRecordByValueRequest"
type="appmsg:CreateInventoryRecordByValueRequestType"/>
<element name="createInventoryRecordByValueResponse"
type="appmsg:CreateInventoryRecordByValueResponseType"/>
<element name="createInventoryRecordByValueResponseException"
In the above XML schema fragment, the CreateInventoryRecordByValueRequest-

Type complex type specifies an element named, <record>, of type of Inventory-
RecordValueType implying the creation of an inventory record managed-entity.
However, the client wishes to create an equipment record managed-entity that is an
extension of inventory record managed-entity. Hence, in the following document,
the client uses the xsi:type attribute in the opening <record> tag to indicate that
the additional elements of the EquipmentRecordValueType are included.
The following is an XML document requesting the creation of the desired equip-
ment record managed-entity:

<appmsg:createInventoryRecordByValueRequest
</appmsg:record>
</appmsg:createInventoryRecordByValueRequest>
The client enqueues the above request onto the message queue for Simple Inven-
tory application and subsequently receives the following instance record in reply
indicating the successful creation of the equipment record managed-entity and the
corresponding equipment record in the inventory:

<appmsg:createInventoryRecordByValueResponse
<appmsg:record>
</appmsg:record>
</appmsg:createInventoryRecordByValueResponse>
Summary
In creating and deleting managed entities, we take advantage of the Managed-Entity

Value pattern (see Sect. 3.1) to reduce the amount of network traffic involved in cre-
ating managed entities, and to reduce the number of operations required to create
and delete multiple managed entities. By arranging the managed-entity value defini-
tions in a type hierarchy, we can exploit the polymorphic features of Java and XML
Schema.
4.3 Managed-Entity Update Pattern
Many management tasks, such as updating inventory records or configuring of sim-

ple equipment, can be supported by a simple read-update model.
Intent
Provide an effective mechanism to support a read-update model.
Fig. 4.3 Use of the Managed-Entity Update Pattern
Motivation
Many OSS applications are amenable to a read-update model of engagement, but

reading or updating a number of attributes with a series of requests can be impracti-
cal because of latency in the network and the communications overhead.
Solution
Use a managed-entity value to read or update multiple attribute values of a managed

entity in a single request. In Fig. 4.3 we show a sequence diagram illustrating how
4.3 Managed-Entity Update Pattern 87
an OSS client might update a managed entity. The client first gets a managed-entity
value corresponding to the managed entity in question. The client updates the fields
of the managed-entity value locally, and then returns the managed-entity value to
the façade with a request to write the new values back to the managed entity and, by
extension, to the managed resource. Only attributes that are to be updated need be
included in the managed-entity value.
Example
OSS Session Profile

Client code, written in Java and using the session profile, to update the attribute
values of a managed entity representing a record in the Simple Inventory might look
like this:
/*
* Update Equipment Record Managed Entity Example
*/
int number, newNumber;
/*
* Get the session bean
*/
/*
* Get an empty Record Key and populate it
*/
//key = ...
/*
* Get an equipment record value object representing the
* equipment record managed-entity indicated
* by the supplied key and print it
*/
null);
//update value-object copy

number = recordvo.getNumberOnHand();
newNumber = number - 1;
recordvo.setNumberOnHand(newNumber);
//and write it back to update the equipment record managed-entity

session.setInventoryRecordByValue(recordvo, false);
//Get the recordvo again and print it

null);
The OSS client creates an instance of a Simple Inventory session bean and re-
quests, from the session bean, an equipment record value-object representing the
equipment record managed-entity indicated by the supplied key. Having received
the equipment record value-object, the client then locally updates the values using
the equipment record value-object interface. The client finally requests that the up-
dated value-object be written back to update the equipment record managed-entity
and hence to update the equipment record that the managed entity represents.
The output might look like this:

Record Id = 42
NumberOnHand = 10
Location = Montreal

Record Id = 42
NumberOnHand = 9
Location = Montreal
OSS Message Profile

In the following JMS example, using the message profile, the client populates a
getInventoryRecordByKey request document with the appropriate key using the
schema fragment shown in Sect. 4 .1 , p. 78 and enqueues it onto the queue for the
Simple Inventory application:

<appmsg:recordKey>
</appmsg:recordKey>
4.3 Managed-Entity Update Pattern 89
In response, the client receives the following value document corresponding to

the equipment record managed-entity associated with the supplied key:

</appmsg:record>
Note that the schema fragment defining the getInventoryRecordByKeyResponse

document in Sect. 4 .1 , p. 78, defines an element named, <record>, of type Inventory-
RecordValueType. However, the type of the <record> element returned is actually
EquipmentRecordValueType, an extension of InventoryRecordValueType; this
is noted by the inclusion of the xsi:type attribute of the <record> element.
The client then updates the number-on-hand locally, and requests the equipment
record managed-entity be updated by enqueueing the following document onto the
Simple Inventory application queue:

<appmsg:setInventoryRecordByValueRequest
</appmsg:record>
</appmsg:setInventoryRecordByValueRequest>
Finally, the client receives the following response document indicating that the
equipment record managed-entity, and the equipment record it represents, have been
updated.

<appmsg:setInventoryRecordByValueResponse
Summary
In reading and updating the attributes of managed entities, we take advantage of the
Managed-Entity Value pattern (see Sect. 3.1) to reduce the amount of network traf-
fic, and to reduce the number of operations required to read and update the attributes
of multiple managed entities.
4.4 Managed-Entity Attribute Population Pattern 91
4.4 Managed-Entity Attribute Population Pattern
Using managed-entity values to read and update the attributes of managed entities,
and to create managed entities themselves, is a consistent way to manage managed
resources irrespective of their implementation. However, a managed entity may ex-
pose a large numbers of attributes, and transferring all of the attribute values in a
managed-entity value, when only a few are required, unnecessarily consumes band-
width. This is particularly a problem when OSS clients make queries or selections
that result in a large number of managed-entities being returned.
OSS clients need a way of specifying a subset of attribute values to be transferred
between an OSS client and OSS application.
Intent
To reduce the unnecessary transfer of attribute values between OSS clients and OSS
applications.
Motivation
Managed entities may contain a large number of attributes and client requests may
result in selecting a large number of managed entities. Transferring all the attribute
values of all of the managed entities either for reading or updating, when only a
subset is required, is an inefficient use of bandwidth.
Solution
Allow the transfer of partially populated managed-entity values. For reading: in-
clude a list of the attribute names that are of interest to the client in the syntax of
all attribute read methods and all query methods. For updating: allow clients to pop-
ulate only those fields corresponding to managed-entities attributes that need to be
updated and to un-populate fields of received managed-entity values. In the session
profile, the client will need to be able to determine which fields are populated.
Example
Revisiting our example of updating an inventory record in Sect. 4.3, we will just
retrieve the NumberOnHand and Location attributes of the equipment record man-
aged entity rather than all of the attributes. We will also un-populate the Location
field before we request the update. (To be sure, not much of a saving in this case!)

Below is the amended example Java code for the session profile: rather than sending
a null as the second parameter to the getInventoryRecordByKey() request, we
send an array of String with two items “NumberOnHand” and “Location”. Before
we request the update, we will use the unPopulate() method to un-populate the
Location field of the managed-entity value.
/*
* Update equipment record managed entity
* with Attribute Selection Example
*/
RecordKey key;
String[] attributeNames;
/*
*/
/*
* Make an Inventory Record Value object, use it to make
* a Record Key, and populate the key
*/
/*
* Get an equipment record value-object representing the
* equipment record managed entity indicated
* by the supplied key retrieving only NumberOnHand and Location
*/
attributeNames = new String[2];
attributeNames[0] =
(EquipmentRecordValue.NUMBERONHAND);
attributeNames[1] =
(EquipmentRecordValue.LOCATION);
attributeNames);
//update local copy of Number on hand

number = recordvo.getNumberOnHand();
recordvo.setNumberOnHand(newNumber);
//unpopulate the Location field

recordvo.unPopulate(EquipmentRecordValue.LOCATION);
//and update the equipment record managed-entity

session.setInventoryRecordByValue(recordvo, false);
4.4 Managed-Entity Attribute Population Pattern 93
Message Profile
Below is the amended getInventoryRecordByKey request document that includes
an additional element, <attributeNames>, with two child elements with content of
“numberOnHand” and “location” respectively indicating that only the numberOn-
Hand and Location managed-entity attributes are to be returned:

<appmsg:recordKey>
<entities:recordType>EquipmentTypeRecord</entities:recordType>
</appmsg:recordKey>
<appmsg:attributeNames>
<appmsg:item>numberOnHand</appmsg:item>
<appmsg:item>location</appmsg:item>
</appmsg:attributeNames>
And the getInventoryRecordByKey response document will look like this:

</appmsg:record>
In the subsequent update of the managed entity, we “un-populate” the attribute

by simply not sending it:

<appmsg:setInventoryRecordByValueRequest

</appmsg:record>
</appmsg:setInventoryRecordByValueRequest>
Summary
The Managed-Entity Attribute Population pattern is a refinement of the Managed-

Entity Update pattern to select only those attribute values that are of interest to
the client thus conserving bandwidth. It is most useful in reducing the number of
attribute values returned in requests that select a large number of managed entities.
4.5 Managed-Entity Template Filter Pattern 95
4.5 Managed-Entity Template Filter Pattern
A typical OSS application will contain a large number of managed resources, and it
is useful for a network operator to be able to target operations on resources based on
their state. For example, a network manager might want to query all line cards that
are currently off-line and start maintenance testing on them, or might want to obtain
a listing of all of the trouble tickets that are outstanding for a particular customer.
Languages to specify such selections, for example formal query languages, can be
difficult to implement and intimidating to use.
In the Managed-Entity model (see Sect. 2.6), managed resources are modelled as
managed entities so OSS clients need a mechanism for selecting managed entities
based on their state.
Intent
Provide a simple mechanism for referencing managed entities based on their

attribute-data state.
Motivation
OSS clients need to be able to make ad hoc selections of managed entities based
on the values of their attributes—that is, an associative look-up. Such selections
can be used to return selected managed-entity values in response to a query, or to
selectively update managed entities.
Solution
Provide an associative look-up mechanism using templates: a client populates a tem-

plate (a managed-entity value) with suitable values and requests the OSS application
to select managed entities whose attribute values match those in the template.
Discussion
The rules for matching are quite straightforward:
• Attribute values and template values that are equal, match (where the values are
complex types, a basis for equality must have been defined).
• Un-populated values in the template are ignored.
• An empty template matches all managed entities of the type of the template (for
example, an empty equipment record value-object or document would match all
equipment records in the Simple Inventory).
• If the managed entities are arranged in a type hierarchy, sub-types of those enti-
ties that are requested in the template will be considered for selection (for exam-
ple an empty inventory record value-object or document would match all records
in the Simple Inventory).
Where template selection is used to return value-objects or documents in response

to say, a query, a client has no way of knowing how many managed-entity value-
objects or documents might be returned so, rather than potentially returning a large
number, the OSS Iterator pattern (see Sect. 3.4) is used to managed the flow.
Example
In the OSS Iterator pattern section, we give an example of using a template to list
all of the equipment items on hand in Montreal, so we will use the same example
here to illustrate the Managed-Entity Template pattern in more detail.

In the following Java example, a managed-entity value-object is used as a template
for selecting all the equipment items on hand in Montreal:
/*
* Managed-entity value iterator/ template pattern example
*
* Return all equipment items and numbers-on-hand in Montreal
*/
EquipmentRecordValue template, equipvo;
/*
*/
/*
* Make an equipment record value object to use as a template
*/
template = (EquipmentRecordValue) session.makeManagedEntityValue(
/*
* Set the location field in the template
*/
template.setLocation("Montreal");
/*
* Request all equipment records where location = "Montreal"
*/
iterator =
session.getInventoryRecordsByTemplate(template, null);
/*
* Process 5 equipment record-value objects at a time
*/
equipvo = (EquipmentRecordValue) recordvos[i];
System.out.println(equipvo.getEquipmentType() + " " +
String.valueOf(equipvo.getNumberOnHand()));
}
recordvos =
}
iterator.remove();
The client code above executes a getInventoryRecordsByTemplate() request

but, because the parameter (i.e. the template) is of type EquipmentRecordValue,
the operation will only match equipment record managed-entities and extended-
equipment record managed-entities.

In the message profile example, an extra element named <template> of type
InventoryRecordValueType is added the request document to carry the values
of the attributes to be matched.

<complexContent>
<sequence>
</sequence>
</extension>
</complexContent>
</complexType>
<complexContent>
<sequence>
</sequence>
</extension>
</complexContent>
</complexType>

To illustrate the use of the Managed-Entity Template pattern in the message pro-
file, we will use the same example as in the session profile example—making a list
of all the equipment items on hand in Montreal. The following XML document re-
quests equipment record value-documents, two at a time, for all equipment records
where the location is “Montreal”. The <appmsg:template> element type in the
document is derived from the type defined by the schema fragment (i.e. Inventory-
RecordValueType) by use of the xsi:type attribute indicating that equipment
record managed-entities and extended-equipment record managed entities are to be
matched.

<appmsg:getInventoryRecordsByTemplateRequest
<appmsg:template xsi:type = "entities:EquipmentRecordValueType">
</appmsg:template>
</appmsg:getInventoryRecordsByTemplateRequest>
The following XML document might be received in response: the value of the
<appmsg:sequence> element indicates that this response is the first of the sequence
and that the value of the <appmsg:endOfReply> element indicates that there are
more responses to come. The xsi:type attribute in the first <appmsg:records>
element indicates that an EquipmentRecordValueType has been returned; the
xsi:type attribute in the second <appmsg:records> element indicates that an
ExtendedEquipmentRecordValueType has been returned. Both are subtypes of
InventoryRecordValueType.

<appmsg:getInventoryRecordsByTemplateResponse
<appmsg:sequence>1</appmsg:sequence>
<appmsg:endOfReply>false</appmsg:endOfReply>
<appmsg:records xsi:type = "entities:EquipmentRecordValueType">

</appmsg:records>
<appmsg:records xsi:type = "entities:ExtendedEquipmentRecordValueType">

<entities:equipmentType>PowerSupply</entities:equipmentType>
<entities:supplierName>Acme</entities:supplierName>
</appmsg:records>
</appmsg:getInventoryRecordsByTemplateResponse>
Summary
The Managed-Entity Template pattern is a simple, but effective, query-by-example

mechanism for the associative addressing of managed entities. In our experience,
it meets the majority of query requirements in telecommunications management.
However, more sophisticated queries can be implemented using the OSS Named-
procedure pattern (see Sect. 3.7).
4.6 Managed-Entity Bulk Update Pattern
There are a number of situations in telecommunications management where a sin-

gle update needs to be applied to multiple managed resources in one request. For
example:
• the configuration of a piece of network equipment that contains a number of
sub-systems that have to be configured at the same time;
• the updating of multiple entries in inventory or trouble-ticket systems in a manner
that preserves consistency; or
• operations where bandwidth is limited and latency an issue.
In the Managed-Entity model (see Sect. 2.6), managed resources are modelled as
managed entities so OSS clients need a mechanism to update multiple managed
entities in one request.
Intent
To provide a mechanism to update multiple managed entities in one request.
Motivation
For reasons of bandwidth conservation, network latency, consistency of result, or

convenience, it is useful for an OSS client to be able to apply a single update to
multiple managed entities into one request.
Solution
Provide bulk managed-entity operations such as:

• Update a number of managed entities with the same attribute values.
• Update a number of managed entities with different attribute values.
• Create a number of managed entities with the same attribute values.
• Create a number of managed entities with different attribute values.
In all cases, atomic execution is assumed—that is either the operation is carried on
all the requested managed entities or it is carried out on none.
Example
In the following example, using the Simple Inventory, we want to update two in-
ventory records to reflect that a number of line cards have been transferred from
4.6 Managed-Entity Bulk Update Pattern 101
Montreal to Toronto. Clearly we must make sure that both updates occur atomically
because if either fails, we will have inconsistencies in the inventory.

The Java client code might look like this (we have ignored error checking for the
sake of clarity):
/*
* Atomic Update of equipment record managed-entity Example
*/
EquipmentRecordValue r1vo, r2vo;
// session = ... set up the session

// key1 = ... set key to Montreal Record
// key2 = ... set key to Toronto record
/*
* Get an equipment record value objects for Montreal and Toronto
*/
r1vo = (EquipmentRecordValue) session.getInventoryRecordByKey(key1,
null);
System.out.println(r1vo.toString());
r2vo = (EquipmentRecordValue) session.getInventoryRecordByKey(key2,
null);
System.out.println(r2vo.toString());
// decrement number on hand of local copy of Montreal record

number = r1vo.getNumberOnHand();
r1vo.setNumberOnHand(newNumber);
// increment number on hand of local copy of Toronto record

number = r2vo.getNumberOnHand();
newNumber = number + 5;
r2vo.setNumberOnHand(newNumber);
//prepare the atomic update

EquipmentRecordValue[] ervos = new EquipmentRecordValue[2];
ervos[0] = r1vo;
ervos[1] = r2vo;
//and atomically update the equipment record managed-entities

try {
session.setInventoryRecordsByValues(ervos);
} catch (ApplicationException e) {
//process exception...
}
The OSS client obtains managed-entity value-objects corresponding to the managed

entities for the Montreal and Toronto records; adjusts the numberOnHand fields of
the value-objects to reflect the equipment transfer; and requests the managed entities
be update atomically with the setInventoryRecordsByValues() operation.

For the message profile, we will use the same example—the atomic update of two
equipment records. First we will define the schema fragments for the setInvento-
ryRecordsByValues request and response documents:

<complexType name="SetInventoryRecordsByValuesRequestType">
<sequence>
<element name="record" type="entities:InventoryRecordValueType"
</sequence>
</complexType>
<complexType name="SetInventoryRecordsByValuesResponseType">
<sequence/>
</complexType>

<element name="setInventoryRecordsByValuesRequest"
type="appmsg:SetInventoryRecordsByValuesRequestType"/>
<element name="setInventoryRecordsByValuesResponse"
type="appmsg:SetInventoryRecordsByValuesResponseType"/>
<element name="setInventoryRecordsByValuesRequestException"
We next use the above schema fragment to define a setInventoryRecordsByVal-

ues instance document with the updated values for the inventory record managed-
entities, and enqueue the document onto the queue for the Simple Inventory appli-
cation:

<appmsg:setInventoryRecordsByValuesRequest
<entities:recordType>EquipmentTypeRecord</entities:recordType>
</appmsg:record>
<entities:recordType>EquipmentType</entities:recordType>
4.6 Managed-Entity Bulk Update Pattern 103
</appmsg:record>
</appmsg:setInventoryRecordsByValuesRequest>
Summary
The Managed-Entity Bulk Update pattern is a convenient way to update a number

of managed entities in one request: it conserves bandwidth and ensures consistency
of updates.
4.7 Last Update-Version-Number Pattern
In a typical telecommunications management network, multiple clients will engage

with the same OSS application to carry out their tasks; for example, a number of
clients could be concurrently updating a trouble-ticket system to indicate progress
in managing and correcting a related problem. Having clients concurrently update
the same trouble ticket can cause inconsistencies.
For example, Client A requests a copy of a trouble ticket and, subsequently,
Client B requests a copy of the same trouble ticket and proceeds to change the
field in her local copy to indicate the trouble has cleared. Client B then updates the
trouble-ticket in the database with all of the values in her local copy. Client A per-
forms similar steps to increase the priority of the ticket, and, on updating the trouble
ticket in the database, overwrites Client B’s change. This situation becomes more
likely the longer the update cycles; in our case, the longer client A takes enter the
new values.
Locking the trouble ticket for the duration of one transaction (read and update),
is a solution, but does suffer from performance problems and permanently locked
records if the client crashes during the transaction.
Intent
Ensure that attribute values of the managed entities remain consistent in the face of
concurrent updates.
Motivation
OSS clients request to update the attribute values of managed entities by sending
populated managed-entity values to OSS applications. Concurrent updating by mul-
tiple clients can cause inconsistencies because of stale values in the managed-entity
values.
Solution
For each managed entity, OSS applications locally maintain a counter, the last-
update-version number, which is incremented each time the managed entity is up-
dated. Each managed-entity value carries a copy of the last-update-version number
set when it was populated by the OSS application. This allows the OSS application
to subsequently detect stale values in a requested update and, in such cases, apply a
policy such as signalling the client. The client could take appropriate action such as
restarting the transaction.
The pattern is based on the Version Number pattern described in Marinescu[1].
References 105
4.8 Final Thoughts
In this book we have examined the case for a pattern-based approach to the design of
interfaces to OSS applications, and have supported the case with over a dozen design
patterns. We have described the design patterns in a technology-neutral manner, but
we have shown the practicality of the approach by giving examples of how each
can be implemented by clients using two different software technologies—JEE and
JMS. But more than that, the technology-neutral descriptions future-proof designs:
the patterns can be bound to new software technologies as they become available.
In Appendix C we show how the Managed-Entity Life Cycle pattern can be bound
to Web Services.
Many of the OSS applications and standards on which we have worked over the
years have successfully used these patterns to make systems integration easier and
more reliable. We believe that were the OSS community to begin to adopt these
patterns, the integration tax—the cost of integrating OSS applications into OSS
solutions—would rapidly fall. Other communities have adopted a pattern-based ap-
proach with great profit—we believe that the OSS community can do the same.
References
1. Marinescu, F., EJB Design Patterns. Wiley, New York, 2002. pp. 70–75.
Appendix A
Type Definitions for the Simple Inventory
The afterthought is good, forethought is better.

Norwegian Proverb
The type definitions for the Simple Inventory application that we have been using,
take different forms for each of the two profiles. In the session profile, we use Java
interface declarations to define the data and operation types, in the message profile
we use XML Schema[1] to define the data message types. The interface diagram for
the Simple Inventory value-objects is shown in Fig. A.1.
A.1 OSS Session Profile Declarations
For the session profile, we have split the declarations into three parts: the dec-
laration of the Simple Inventory value-object interfaces, the declarations of the
façade operations, and the declarations of the interfaces to the event notifica-
tion object-messages. The Java declarations for the RecordKey, ManagedEntity-
Value, InventoryRecordValue, EquipmentRecordValue, ExtendedEquipmen-
tRecordValue, and SupplierRecordValue value-object interfaces are as follows:
/**
*
* Record-key inteface declaration
*/
public interface RecordKey extends java.io.Serializable {
/**
* the managed-entity record key
*/
public static final String RECORDTYPE = "RecordType";
public static final String RECORDID = "RecordId";
/**
* Accessors and mutators for fieldsSet
*/
public void setRecordId(String id);
public String getRecordId();
public void setRecordType(String type);
public String getRecordType();

}
107
108 A Type Definitions for the Simple Inventory
Fig. A.1 Simple Inventory Value-Object Interface Diagram
/**
* Managed-entity value-object interface declaration.
*
* This the base interface for all managed-entity value-objects.
*/
public interface ManagedEntityValue extends java.io.Serializable {
//public interface ManagedEntityValue {
/**
* the managed-entity value-object
*/
public static final String LASTUPDATEVERSIONNUMBER =
"LastUpdateVersionNumber";
A.1 OSS Session Profile Declarations 109
public static final String RECORDKEY = "RecordKey";
/**
* Managed-entity value is a factory for record keys
*/
public RecordKey makeRecordKey();
/**
* Accessors and mutators for fields
*/
public RecordKey getRecordKey();
public void setRecordKey(RecordKey key);
public long getLastUpdateVersionNumber();
public void setLastUpdateVersionNumber(long lastUpdateNumber);
/**
* Get managed-entity attribute/value pairs
*/
public java.util.Hashtable getAttributeValues(String[] names)
/**
* Get managed-entity attribute names
*/
public String[] getAttributeNames();
/**
* Attribute population methods
*/
public void unPopulate(String attributeName);
public boolean isPopulated(String attributeName);

}
/**
* Inventory record value-object interface declaration.
*
* This the base interface for all Simple Inventory Record value-objects.
* The fields of the value object carry copies of the values
* of the attributes of the Inventory Record managed entities.
*/
public interface InventoryRecordValue extends ManagedEntityValue{
/**
* Constant to identify the field of
* the inventory record value-object
*/
public static final String CREATIONDATE = "RecordCreationDate";
/**
* Accessors for field
*/
public Calendar getRecordCreationDate();
}
/**
* Equipment record value-object interface declaration
*/
public interface EquipmentRecordValue
/**
* Constants to identify the fields of the equipment record value-object
*/
public final static String EQUIPMENTTYPE = "EquipmentType";
public final static String NUMBERONHAND = "NumberOnHand";
public final static String LOCATION = "Location";
/*
* Accessors and mutators for the fields of the value-object
*/
void setEquipmentType(String equipmentType);
String getEquipmentType();
void setNumberOnHand(int numberOnHand);
int getNumberOnHand();
void setLocation(String aLocation);
String getLocation();
}
/**
* Extended-equipment record value-object interface declaration
*/
public interface ExtendedEquipmentRecordValue
extends EquipmentRecordValue {
/**
* Constants to identify the extended-equipment record
* fields (attributes)
*/
public final static String REORDERLEVEL = "ReorderLevel";
public final static String SUPPLIERNAME = "SupplierName";
void setReorderLevel(int reorderLevel);
int getReorderLevel();
}
/**
* Supplier record value object interface
*/
public interface SupplierRecordValue
/**
* Constants to identify the fields of the supplier record value-object
*/
A.1 OSS Session Profile Declarations 111
public final static String NAME = "SupplierName";

public final static String ADDRESS = "SupplierAddress";
public final static String CONTACTNUMBER = "ContactNumber";
/**
* Accessor and mutators for the fields of the value-object
*/
void setSupplierAddress(String supplierAddress);
String getSupplierAddress();
void setContactNumber(String aTelephoneNumber);
String getContactNumber();
}
The Java declaration for the OSS Session Façade interface is as follows:
/**
* Simple Inventory session bean declaration.
*
* This interface defines the operational aspects of the Simple
* Inventory session bean that implements the facade pattern.
*/
@Remote
public interface SimpleInventorySession
{
public ManagedEntityValue makeManagedEntityValue(

public InventoryRecordValue getInventoryRecordByKey(

RecordKey key, String[] attrNames)
public InventoryRecordValueIterator getInventoryRecordsByTemplate(

InventoryRecordValue template,
String[] attributeNames) throws ApplicationException;
public void setInventoryRecordByValue(

InventoryRecordValue value, boolean resyncRequired)
public void setInventoryRecordsByValues(InventoryRecordValue[] recordvos)

public RecordKey createInventoryRecordByValue(

InventoryRecordValue value)
public void removeInventoryRecordByKey(RecordKey key)

public String[] getManagedEntityTypes()

public NamedProcedureRequest makeNamedProcedureRequest(

public NamedProcedureResponse execute(NamedProcedureRequest namedProcedure)

}
The Java declarations for the event-notification interfaces are as follows:
/**
* Base interface to access the payload of all Simple
* Inventory event notification messages
*/
public interface BaseEvent extends java.io.Serializable {
/*
* Accessor for the time the event was published as a String
*/
public String getEventTimeAsString();
/*
* Accessor for the time the event was published
*/
public Calendar getEventTime()
}
/**
* Interface to access the payload
* of the record-create notification
*/
public interface RecordCreateEvent extends BaseEvent {
/*
* Accessor/mutator for the record created
*/
public InventoryRecordValue getInventoryRecordValue()
public void setInventoryRecordValue(InventoryRecordValue value)

}
A.2 OSS Message Profile Declarations
The XML definitions for the Simple Inventory application are split into two schemata:
the first, Entities.xsd, defines the inventory record complex-types and element
types, and the second, Appmsg.xsd, the message and notification complex-types
and element-types supported by the message profile.
The schema for inventory record complex-types and element types is as follows:
<schema targetNamespace="http://xml.netbeans.org/schema/Entities"
xmlns:entities="http://xml.netbeans.org/schema/Entities"
xmlns:tns="http://xml.netbeans.org/schema/Entities"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">

<sequence>
</sequence>
</complexType>

<sequence>
</sequence>
</complexType>

<complexContent>
<sequence>
</sequence>
</extension>
</complexContent>
</complexType>

<complexContent>
<sequence>
</sequence>
</extension>
</complexContent>
</complexType>

<complexType name="SupplierRecordValueType">
<complexContent>
<sequence>
<element name="supplierName" type="string" minOccurs="0"/>
<element name="supplierAddress" type="string" minOccurs="0"/>
<element name="contactNumber" type="string" minOccurs="0"/>
</sequence>
</extension>
</complexContent>
</complexType>

<complexType name="ExtendedEquipmentRecordValueType">
<complexContent>
<extension base="entities:EquipmentRecordValueType">
<sequence>
<element name="reorderLevel" type="int"/>
<element name="supplierName" type="string"/>
</sequence>
</extension>
</complexContent>
</complexType>

<element name="inventoryRecordKey" type="entities:RecordKeyType"/>
<element name="managedEntityValue" type="entities:ManagedEntityValueType"/>
<element name="inventoryRecordValue" type="entities:InventoryRecordValueType"/>
<element name="extendedEquipmentRecordValue"
type="entities:ExtendedEquipmentRecordValueType"/>
<element name="supplierRecordValue" type="entities:SupplierRecordValueType"/>
</schema>
The schema for the message and notification complex-types and element-types
is as follows:
<schema targetNamespace="http://xml.netbeans.org/schema/appmsg"
xmlns:entities="http://xml.netbeans.org/schema/Entities"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:appmsg="http://xml.netbeans.org/schema/appmsg"
xmlns="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<import namespace="http://xml.netbeans.org/schema/Entities"
schemaLocation="EntitiesOld.xsd"/>

<sequence>
</sequence>
</complexType>
<sequence>
</sequence>
</complexType>


<sequence>
</sequence>
</complexType>
<sequence>
</sequence>
</complexType>

<element name="getInventoryRecordByKeyResponseException"

<complexType name="SetInventoryRecordByValueRequestType">
<sequence>
</sequence>
</complexType>
<complexType name="SetInventoryRecordByValueResponseType">
<sequence/>
</complexType>

<element name="setInventoryRecordByValueRequest"
type="appmsg:SetInventoryRecordByValueRequestType"/>
<element name="setInventoryRecordByValueResponse"
type="appmsg:SetInventoryRecordByValueResponseType"/>
<element name="setInventoryRecordByValueRequestException"

<complexType name="SetInventoryRecordsByValuesRequestType">
<sequence>
<element name="record" type="entities:InventoryRecordValueType"
</sequence>
</complexType>
<complexType name="SetInventoryRecordsByValuesResponseType">
<sequence/>
</complexType>

<element name="setInventoryRecordsByValuesRequest"
type="appmsg:SetInventoryRecordsByValuesRequestType"/>
<element name="setInventoryRecordsByValuesResponse"
type="appmsg:SetInventoryRecordsByValuesResponseType"/>
<element name="setInventoryRecordsByValuesRequestException"

<complexType name="RemoveInventoryRecordByKeyRequestType">
<sequence>
<element name="inventoryRecordKey" type="entities:RecordKeyType"
nillable="false"/>
</sequence>
</complexType>
<complexType name="RemoveInventoryRecordByKeyResponseType">
<sequence/>
</complexType>

<element name="removeInventoryRecordByKeyRequest"
type="appmsg:RemoveInventoryRecordByKeyRequestType"/>
<element name="removeInventoryRecordByKeyResponse"
type="appmsg:RemoveInventoryRecordByKeyResponseType"/>
<element name="removeInventoryRecordByKeyResponseException"

<complexType name="ApplicationFaultType">
<sequence>
<element name="errorMessage" type="string"/>
</sequence>
</complexType>
<element name="applicationFault" type="appmsg:ApplicationFaultType"/>

<complexType name="ArrayOfString">
<sequence>
<element name="item" type="string" nillable="true" maxOccurs="unbounded"/>
</sequence>
</complexType>

<complexType name="IteratorRequest" abstract="false">
<sequence>
<element name="n" type="unsignedInt" nillable="true" minOccurs="0"/>
</sequence>
</complexType>
<complexType name="IteratorResponse" abstract="false">

<sequence>
<element name="sequence" type="int"/>
<element name="endOfReply" type="boolean"/>
</sequence>
</complexType>

<complexContent>
<sequence>
</sequence>
</extension>
</complexContent>
</complexType>
<complexContent>
<sequence>
</sequence>
</extension>
</complexContent>
</complexType>


<xsd:complexType name="NamedProcedureRequestType">
<xsd:sequence/>
</xsd:complexType>
<xsd:complexType name="NamedProcedureResponseType">
<xsd:sequence/>
</xsd:complexType>
<xsd:element name="namedProcedureRequest"
type="appmsg:NamedProcedureRequestType"/>
<xsd:element name="namedProcedureResponse"
type="appmsg:NamedProcedureResponseType"/>

<xsd:complexType name="IteratorNamedProcedureRequestType">
<xsd:extension base="appmsg:NamedProcedureRequestType">
<xsd:sequence>
<element name="iteratorRequest" type="appmsg:IteratorRequest"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexType>
<xsd:complexType name="IteratorNamedProcedureResponseType">
<xsd:extension base="appmsg:NamedProcedureResponseType">
<xsd:sequence>
<element name="iteratorResponse" type="appmsg:IteratorResponse"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexType>
<xsd:element name="iteratornamedProcedureRequest"
type="appmsg:IteratorNamedProcedureRequestType"/>
<xsd:element name="IteratorNamedProcedureResponse"
type="appmsg:IteratorNamedProcedureResponseType"/>

<xsd:complexType name="QueryReorderItemsRequestType">
<xsd:extension base="appmsg:IteratorNamedProcedureRequestType">
<xsd:sequence>
<xsd:element name="location" type="xsd:string"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexType>
<xsd:complexType name="QueryReorderItemsResponseType">
<xsd:extension base="appmsg:IteratorNamedProcedureResponseType">
<xsd:sequence>
<xsd:element name="records"
type="entities:ExtendedEquipmentRecordValueType"
</xsd:sequence>
</xsd:extension>
</xsd:complexType>
<xsd:element name="queryReorderItemsResponse"
type="appmsg:QueryReorderItemsResponseType"/>
<xsd:element name="queryReorderItemsRequest"
type="appmsg:QueryReorderItemsRequestType"/>
<xsd:element name="namedProcedureException"

<xsd:complexType name="BaseEventNotifcationType">
<xsd:sequence>
<xsd:element name="eventTime" type="xsd:date" nillable="false"/>
</xsd:sequence>
</xsd:complexType>

<xsd:complexType name="RecordCreateEventType">
<xsd:sequence>
</xsd:sequence>
</xsd:extension>
</xsd:complexType>

<xsd:element name="recordCreateEventNotification"
type="appmsg:RecordCreateEventType"/>

<xsd:complexType name="RecordDeleteEventType">
<xsd:sequence>
</xsd:sequence>
</xsd:extension>
</xsd:complexType>

<xsd:element name="recordDeleteEventNotification"
type="appmsg:RecordDeleteEventType"/>
</schema>
Appendix B
Implementing an OSS Client Using JAXB
To illustrate the use of patterns in the OSS Message Profile, we have shown exam-
ples of the XML messages that a client might use to access OSS applications via a
message-driven bean (see Fig. 3.5, p. 39).
For the sake of clarity, we have not shown any supporting code for generating
the messages, enqueueing the messages, or receiving responses. Within the JEE
platform, there are a number tools and APIs that help in the development of Java-
based clients using the message profile. In this chapter we will show how an OSS
client might create an equipment record managed-entity within the message profile
using Java and the JAXB API. We will also look at the overall implementation
architecture for implementing OSS Message Profile using JEE.
B.1 Create Equipment Record Managed-Entity Example
The Java Architecture for XML Binding (JAXB[2]) API is a framework for pro-
cessing XML documents within the Java programming language. The API provides
methods for un-marshalling an XML document into a tree of Java objects and, con-
versely, for marshalling Java objects to an XML message. The Java type information
is normally obtained by compiling the relevant XML schema into Java classes by
the use of the JAXB binding complier[3].
In the following example, we will show the use of the JAXB API to create
an equipment record managed-entity (q.v. Sect. 4.2) in the Simple Inventory. The
first step is to compile the relevant XML schemata into Java classes and make the
classes available to the OSS client as a package. The schema fragments for the Cre-
ateInventoryRecordByValue request and response complex types and Equip-
mentRecordValueType complex types are as follows.
121
122 B Implementing an OSS Client Using JAXB
First, the CreateInventoryRecordByValue request and response complex types

and elements:

<sequence>
</sequence>
</complexType>
<sequence>
</sequence>
</complexType>

And next, the managed-entity value-types:

<sequence>
</sequence>
</complexType>

<sequence>
</sequence>
</complexType>

<complexContent>
<sequence>
</sequence>
</extension>
B.1 Create Equipment Record Managed-Entity Example 123
</complexContent>
</complexType>

<complexContent>
<sequence>
</sequence>
</extension>
</complexContent>
</complexType>
The following code fragment creates and populates the JAXB equivalents of the
CreateInventoryRecordByValueRequestType, the RecordKeyType, and the Equip-
mentRecordValueType:
public void createInventoryByValue() throws JMSException {

ObjectFactory objFactory = new ObjectFactory();
// Create a JAXB create-inventory-record-by-value request object

CreateInventoryRecordByValueRequestType value = objFactory.
createCreateInventoryRecordByValueRequestType();
// Create a JAXB equipment record object and populate it

EquipmentRecordValueType rvalue = new EquipmentRecordValueType();
rvalue.setLocation("Montreal");
rvalue.setEquipmentType("LineCard");
rvalue.setNumberOnHand(new Integer(10));
//Create a RecordKey object and populate it

RecordKeyType rkXml = new RecordKeyType();
rkXml.setRecordId("42");
rkXml.setRecordType("EquipmentRecordType");
// Set the key field of the equipment record object

rvalue.setRecordKey(rkXml);
// Set the equipment record field of the request object

value.setRecord(rvalue);
The next step is to wrap the request object in its XML element and write it out:
JAXBContext jaxbContext = null;

JAXBElement<CreateInventoryRecordByValueRequestType> request = objFactory.
createCreateInventoryRecordByValueRequest(value);
try {
jaxbContext = JAXBContext.newInstance("org.netbeans.xml.schema.appmsg");
} catch (JAXBException ex) {
Logger.getLogger(JMSClient.class.getName()).log(Level.SEVERE, null, ex);
}
Marshaller marshaller = null;
// Create the marshaller that writes the XML file from the Java objects
try {
marshaller = jaxbContext.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
}
// Write the XML file

StringWriter writer = new StringWriter();
try {
marshaller.marshal(request, writer);
System.out.println("XML File to be enqueued = \n" + writer.toString());
}
And finally to start the connections, enqueue the message, and wait for the response:
/*
* Start connection to the message queues and consumer
*/
try {
connection = simpleInventoryQueueFactory.createConnection();
connection.start();
MessageConsumer consumer = session.createConsumer(replyToDestinationQueue);
//Send the message to Simple Inventory queue

sendJMSMessageToSimpleInventoryQueue(writer.toString());
//Wait for the reponse on replyToDestination

Message msg = consumer.receive();
System.out.println("Received Message=" + msg.toString());
The request message generated and sent by the client to the message-driven bean
will look like this:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<ns2:createInventoryRecordByValueRequest
xmlns:ns2="http://xml.netbeans.org/schema/appmsg"
xmlns="http://xml.netbeans.org/schema/Entities">
<ns2:record xsi:type="EquipmentRecordValueType"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<recordKey>
<recordId>42</recordId>
<recordType>EquipmentRecordType</recordType>
</recordKey>
<equipmentType>LineCard</equipmentType>
<numberOnHand>10</numberOnHand>
<location>Montreal</location>
</ns2:record>
</ns2:createInventoryRecordByValueRequest>
B.2 Message Profile Implementation Software Architecture 125
And the response received by the client will look like this:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<ns2:createInventoryRecordByValueResponse
<ns2:record>
</ns2:record>
</ns2:createInventoryRecordByValueResponse>
B.2 Message Profile Implementation Software Architecture
Fig. B.1 Using JAXB to Create an Equipment Record Managed-Entity
In the message profile example described in Sect. 3.2, the OSS Façade is imple-
mented by means of a message-drive bean that intercepts XML messages and makes
the appropriate method calls on the OSS application. Fig. B.1 shows a more detailed
software architecture with the session bean and the marshalling and un-marshalling
components. The sequence of operations is as follows:
1. Using the JAXB packages and the JAXB API, the OSS client builds a create-
inventory-record-managed-entity XML request and enqueues it onto the Simple
Inventory queue as described in Sect B.1.
2. Using an implementation of the onMessage() method, the message-driven bean
retrieves the XML message from the queue.
3. Using the JAXB API, the message-driven bean un-marshals the XML message
into a tree of objects.
4. The message-drive bean builds the createInventoryRecordByValue() method

and calls the session bean.
5. The session bean executes the method on the OSS application and forwards the
response from the OSS application to the message-driven bean.
6. The message-driven bean marshals the response into an XML message.
7. The message-driven bean enqueues the XML message onto the reply queue.
8. The OSS client retrieves the response from the queue.
B.3 Create Equipment Record Managed-Entity

Example—Complete Code
Here is the complete code for the create equipment record managed-entity example:
import java.io.StringWriter;
import java.util.logging.Level;
import java.util.logging.Logger;
import javax.jms.Connection;
import javax.jms.ConnectionFactory;
import javax.jms.JMSException;
import javax.jms.Message;
import javax.jms.MessageConsumer;
import javax.jms.MessageProducer;
import javax.jms.Queue;
import javax.jms.Session;
import javax.jms.TextMessage;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBElement;
import javax.xml.bind.JAXBException;
import javax.xml.bind.Marshaller;
import org.netbeans.xml.schema.appmsg.CreateInventoryRecordByValueRequestType;
import org.netbeans.xml.schema.appmsg.ObjectFactory;
import org.netbeans.xml.schema.entities.EquipmentRecordValueType;
import org.netbeans.xml.schema.entities.RecordKeyType;
/**
*
* Example OSS client--message profile
*/
public class JMSClient {
Queue simpleInventoryQueue, replyToDestinationQueue;

ConnectionFactory simpleInventoryQueueFactory;
public static void main(String[] args) {

JMSClient main = new JMSClient();
main.init();
try {
main.createInventoryByValue();
}
}
private Connection connection;
B.3 Create Equipment Record Managed-Entity Example—Complete Code 127
private Session session;
/**
* Example of creating an equipment record managed-entity-
* by-value XML document using JAXB and sending it to the
* Simple Inventory application using JMS
*
* The schemata for XML message types and entity types have
* been compile to generate the following Java classes:
*
* CreateInventoryRecordByValueRequestType;
* EquipmentRecordValueType;
* RecordKeyType; and
* ObjectFactory.
*
*/
public void createInventoryByValue() throws JMSException {
ObjectFactory objFactory = new ObjectFactory();
// Create a JAXB create-inventory-record-by-value request object

CreateInventoryRecordByValueRequestType value = objFactory.
createCreateInventoryRecordByValueRequestType();
// Create a JAXB equipment record object and populate it

EquipmentRecordValueType rvalue = new EquipmentRecordValueType();
rvalue.setLocation("Montreal");
rvalue.setEquipmentType("LineCard");
rvalue.setNumberOnHand(new Integer(10));
//Create a RecordKey object and populate it

RecordKeyType rkXml = new RecordKeyType();
rkXml.setRecordId("42");
rkXml.setRecordType("EquipmentRecordType");
// Set the key field of the equipment record object

rvalue.setRecordKey(rkXml);
// Set the equipment record field of the request object

value.setRecord(rvalue);
/*
* Wrap the request in its XML element and write it out
*
*/
JAXBContext jaxbContext = null;
JAXBElement<CreateInventoryRecordByValueRequestType> request = objFactory.
createCreateInventoryRecordByValueRequest(value);
try {
jaxbContext = JAXBContext.newInstance("org.netbeans.xml.schema.appmsg");
}
Marshaller marshaller = null;
// Create the marshaller that writes the XML file from the Java objects
try {
marshaller = jaxbContext.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
}
// Write the XML file

StringWriter writer = new StringWriter();
try {
marshaller.marshal(request, writer);
System.out.println("XML File to be enqueued = \n" + writer.toString());
}
/*
* Start connection to the message queues and consumer
*/
try {
connection = simpleInventoryQueueFactory.createConnection();
connection.start();
MessageConsumer consumer = session.createConsumer(replyToDestinationQueue);
//Send the message to Simple Inventory queue

sendJMSMessageToSimpleInventoryQueue(writer.toString());
//Wait for the reponse on replyToDestination

Message msg = consumer.receive();
System.out.println("Received Message=" + msg.toString());
} finally {
if (session != null) {
try {
session.close();
} catch (JMSException e) {
Logger.getLogger(this.getClass().getName()).log(Level.WARNING,
"Cannot close session", e);
}
}
if (connection != null) {
connection.close();
}
}
System.exit(0);
/**
* Create and populate a message to send to the Simple Inventory
*/
private Message createJMSMessageForJMSSimpleInventoryQueue(Session session,
String messageData) throws JMSException {
TextMessage tm = session.createTextMessage();
tm.setText(messageData);
return tm;
}
/**
* Send a message to the Simple Inventory Queue
*/
private void sendJMSMessageToSimpleInventoryQueue(String messageData) throws
JMSException {
MessageProducer messageProducer = session.createProducer(
simpleInventoryQueue);
messageProducer.send(createJMSMessageForJMSSimpleInventoryQueue(session,
messageData));
}
/**
* Initialize name resolution and connections
*/
public void init() {
Context jndiContext = null;
B.3 Create Equipment Record Managed-Entity Example—Complete Code 129
String destName = "jms/simpleInventoryQueue";

String replyToDestName = "jms/replyToDestinationQueue";
System.out.println("Destination name is " + destName);
/*
* Create a JNDI API InitialContext object if none exists
*/
try {
jndiContext = new InitialContext();
} catch (NamingException ex) {
}
/*
* Look up connection factory and destination.
*/
try {
simpleInventoryQueueFactory = (ConnectionFactory) jndiContext.lookup(
"jms/simpleInventoryQueueFactory");
simpleInventoryQueue = (Queue) jndiContext.lookup(destName);
replyToDestinationQueue = (Queue) jndiContext.lookup(replyToDestName);
} catch (Exception e) {
System.out.println("JNDI API lookup failed: " + e.toString());
System.exit(1);
}
}
}
Appendix C
Binding the OSS Patterns to Web Services
In describing the two OSS Implementation Profiles (see Sect. 2.5), we chose to
describe the OSS Message Profile by binding the OSS Design Patterns to JMS—
that is describing OSS clients that use XML messages carried by JMS. In order to
demonstrate the flexibility of our pattern-based approach, we will show how the
OSS Design Patterns can be bound to Web Services, see Fig. C.1.
Fig. C.1 Binding the OSS Reference Architecture to Web Services
The goal of Web Services[4] is that of seamless, loosely-coupled interoperability

of heterogeneous applications irrespective of the implementation platform or pro-
gramming language. Telecommunications service-providers can take advantage of
the benefits for both inter- and intra-company application integration. Web Services
are a popular way of implementing Service Oriented Architecures (SOA)[5].
Web Services rely on two key technologies:
Web Services Definition Language (WSDL)[6] an XML grammar that is used to
describe the services offered by a Web Service; and
Simple Object Access Protocol (SOAP)[7] a standard packaging structure for
transferring XML documents over various transport protocols (often HTTP).
131
132 C Binding the OSS Patterns to Web Services
Defining a Web Service in WSDL

WSDL specifications are build up of a number of XML elements, namely:
<message> element defines the messages to be exchanged between the OSS client
and the Web Services endpoint.
<operation> element defines the request, response, and exception messages as-
sociated with an operation.
<portType> element defines the subset of operations supported by the Web Ser-
vices endpoint.
<binding> element defines the binding to the carriage protocol (e.g. SOAP).
<service> element defines the location of the Web Service—it is an implementa-

tion of one or more <portType>.
Example
To illustrate how we might use WSDL to define Web Service, we will use the same
example as we used in Sect. B.1, that is, from the Managed-Entity Life Cycle pat-
tern, the creation of an equipment record managed-entity (q.v. Sect. 4.2) in the Sim-
ple Inventory.
First we will define the request, response, and exception <message> elements by
re-using the element definitions in the OSS Message Profile (see Sect. A.2):

<message name="createInventoryRecordByValueOperationRequest">
<part name="createInventoryRecordByValueRequest"
element="appmsg:createInventoryRecordByValueRequest"/>
</message>
<message name="createInventoryRecordByValueOperationResponse">
<part name="createInventoryRecordByValueResponse"
element="appmsg:createInventoryRecordByValueResponse"/>
</message>
<message name="createInventoryRecordByValueOperationFault">
<part name="createInventoryRecordByValueRequestException"
element="appmsg:createInventoryRecordByValueResponseException"/>
</message>
C Binding the OSS Patterns to Web Services 133
We next define <portType> element with one <operation> element, namely

createInventoryRecordByValueOperation:

<portType name="CreateInventoryRecordByValuePortType">
<operation name="createInventoryRecordByValueOperation">
<input name="input1"
message="tns:createInventoryRecordByValueOperationRequest"/>
<output name="output1"
message="tns:createInventoryRecordByValueOperationResponse"/>
<fault name="fault1"
message="tns:createInventoryRecordByValueOperationFault"/>
</operation>
</portType>
And, finally, we bind the <portType> element to SOAP in the document/literal

style:

<binding name="CreateInventoryRecordByValueBinding"
type="tns:CreateInventoryRecordByValuePortType">
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="createInventoryRecordByValueOperation">
<soap:operation/>
<input name="input1">
<soap:body use="literal"/>
</input>
<output name="output1">
<soap:body use="literal"/>
</output>
<fault name="fault1">
<soap:fault use="literal" name="fault1"/>
</fault>
</operation>
</binding>
A SOAP message to create an equipment record managed entity might look like
this:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" >
<soapenv:Header/>
<soapenv:Body>
<ns2:createInventoryRecordByValueRequest
<ns2:record xsi:type="EquipmentRecordValueType"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
134 C Binding the OSS Patterns to Web Services
<recordKey>
</recordKey>
<equipmentType>LineCard</equipmentType>
<numberOnHand>10</numberOnHand>
<location>Montreal</location>
</ns2:record>
</ns2:createInventoryRecordByValueRequest>
</soapenv:Body>
</soapenv:Envelope>

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" >
<soapenv:Header/>
<soapenv:Body>
<ns2:createInventoryRecordByValueResponse
<ns2:record>
</ns2:record>
</ns2:createInventoryRecordByValueResponse>
</soapenv:Body>
</soapenv:Envelope>
Appendix D
OSS Design Pattern Interaction and Usage
The various patterns that we have introduced in this book do not stand alone: many
are related and many rely on other patterns. To help the reader understand the rela-
tionships we show them in graphical format.
D.1 OSS Design Pattern Interaction
In the two pattern interaction diagrams, Figs. D.1a and D.1b, we show the relation-
ships between the patterns. The nodes of the graphs represent the patterns and the
edges the relationships.
Fig. D.1a OSS Pattern Interactions
135
136 D OSS Design Pattern Interaction and Usage
Fig. D.1b OSS Pattern Interactions cont.

References 137
D.2 OSS Design Pattern Usage
In Fig. D.2 we show the usage of the patterns by OSS clients and OSS applications.
The patterns supporting the OSS Application Services set the overall, coarse-grained
architectural structure for an OSS solution. The patterns supporting the Managed-
Entity Services allow the fine-grained access to the managed entities. OSS clients
will engage with the OSS Application Services to set up the context of the data
transfers using the patterns supporting the Data Transfer Services.
Fig. D.2 OSS Pattern Usage
References

2. Java Architecture for XML Binding, GlassFish Community, https://jaxb.dev.java.net.
3. Java Architecture for XML Binding Tutorial, Java Developer Network,
https://jaxb.dev.java.net/tutorial/section 1 1-Introduction.html#About JAXB.
5. Reference Model for Service Oriented Architecture 1.0, Organization for the Advancement
of Structured Information Standards (OASIS),
http://docs.oasis-open.org/soa-rm/v1.0/soa-rm.pdf.
6. Web Services Description Language, World Wide Web Consortium,
http://www.w3.org/TR/2007/REC-wsdl20-primer-20070626/.
7. Simple Object Access Protocol, World Wide Web Consortium,
http://www.w3.org/TR/2007/REC-soap12-part0-20070427/.
Glossary
architectural pattern A design pattern that addresses a problem encountered in

developing the overall software architecture.
architectural style An abstract description of software components and the pattern
of runtime control and data transfer; examples include client-server, event-based,
and communicating processes.
configuration The setting of the parameters that control the functioning of the net-
work or services.
connectivity resource A software and hardware asset that provide transmission,
multiplexing, or switching services.
Customer Relationship Management A suite of processes and software applica-
tions to support customer-service representatives; examples of applications include
service activation, billing, and problem reporting and tracking.
design pattern A description, in a technology-neutral manner, of the essence of a
proven and practical solution to a recurring programming or architectural problem.
Digital Subscriber Loop (DSL) A family of technologies that provide digital data
transmission over the wires of a local telephone network.
Element Management System (EMS) A computer system that manages one or
more network elements normally in some sort of sub-network arrangement.
end-user application An application, offered to an end user, that leverages the con-
nectivity of the network—applications such as email, website hosting, data storage,
personal messaging, and web conferencing.
implementation profile A description of the non-functional aspects of the engage-
ment style between an OSS client and an OSS application.
information model A model of information elements, their inter-relationships, and
their behaviour.
139
140 Glossary
Java Platform, Enterprise Edition (JEE)TM An environment for developing and

deploying enterprise applications.
Java Message Service (JMS)TM An API for invoking operations on enterprise
messaging systems.
Long Term Evolution (LTE) The fourth generation mobile broadband standard.
managed entity A model of the management aspects of managed resource; it is by
engaging with a managed entity that the corresponding managed resource is man-
aged.
managed resource A logical or physical asset that provides a service within the
telecommunications network and is manageable; examples of assets include con-
nectivity resources, end-user applications, and support resources.
managed system A computer system that hosts or manages managed resources;
managed systems can be Element Management Systems (EMSs) that manage one
or more connectivity resources, or they can be systems that host resources or end-
user services such as inventories, trouble tickets, or email services.
managed-entity value A data item that is used as a surrogate for a managed entity
and is passed between an OSS client and an OSS application.
Management Integration System A server that hosts management-integration ap-
plications.
management solution A coordination of manual procedures and the functional-
ity of OSS applications that addresses a particular management problem; examples
include service fulfillment, problem resolution, and the provisioning of network fa-
cilities.
management-integration application A software component that coordinates the
functionality of OSS applications to deliver a management solution.
Network Element (NE) A combination of hardware and software that provides
switching, multiplexing, or transmission services.
notification service A software component that delivers event reports asynchronously
to OSS clients.
Operations Support System (OSS) A server that hosts OSS applications.
operator system A workstation that hosts the user interface and applications that
support the human operator in carrying out his/her management tasks.
operator-support application A software component that is responsible for operator-
task workflow and validation of operator input.
OSS application A software component that manages a particular aspect of a
telecommunications system such as a connectivity resource, an end-user service,
or a support resource; the OSS application implements the management logic and
business rules derived from an analysis of the management requirements.
Glossary 141
OSS client A software component that engages with a remote OSS application to
access the latters functionality.
OSS Design Pattern A description of an abstract architectural or programming
solution to telecommunications management problem that has proven successful in
practice.
OSS Façade A view, in terms of remote operations, exposed by an OSS applica-
tion.
OSS integration interface The interface at which OSS application functionality is
made available.
OSS Message Profile A description of the non-functional aspects of a message-
oriented engagement between an OSS client and an OSS application.
OSS Reference Architecture A refinement of an architectural style in terms of
interaction patterns, granularity of operation, and client-server separation; it is a
mapping of the OSS Reference Model into the architectural style.
OSS Reference Model A functional decomposition that meets telecommunica-
tions management requirements.
OSS Session Profile A description of the non-functional aspects of a session-
oriented engagement between an OSS client-component and an OSS application.
programming pattern A design pattern that addresses a problem encountered
within the overall framework of the software architecture.
session-oriented data exchange A style of data exchange between a client and a
remote application that includes a preamble to agree the rules for the exchange.
sessionless data exchange A style of data exchange between a client and a remote
application that does not include any preamble to agree the rules for the exchange;
the client normally includes a call-back address for replies.
software architecture The specification of the systems architecture in terms of
programming and data elements bound to a particular software technology.
support resource An asset that supports the revenue-generating services; support
resources include trouble tickets, alarm reports, and customer and billing records.
systems architecture The architecture of the system that is actually deployed; it
may be a direct realization of the software architecture, but may also be comple-
mented by deployment considerations such as clustering and virtualization.
142 Glossary
telecommunications management system A system of distributed computers that

supervises and manages a telecommunications network and related services.
telecommunications service A service offered by a service provider to customers
that leverages a telecommunications network; examples include connectivity ser-
vices and end-user applications.
value type An entity which shares many of the characteristics of interfaces. It is a
description of both a set of operations that a client may request and of state that is
accessible to a client. Instances of a value type are always local concrete implemen-
tations. A value type, in addition to the operations and state defined for itself, may
also inherit from other value types, and through inheritance support other interfaces.
XML Schema An XML Language for defining the content of XML documents.
About the Authors
Pierre Gauthier is the President and CTO of OSS Wave, a software consulting
and training company. For the last decade Pierre has been involved in the design
and development of software for telecommunications and Operation Support
Systems (OSSs), holding senior positions with Oracle and Nortel. Pierre was the
driving force behind the development of the OSS/J Design Guidelines and is Spec
Lead for JSR 91, the OSS Trouble Ticket API. Pierre is a JavaOne alumnus,TMF
invited speaker, and JCP Star Spec Lead.
He holds a master’s degree in Electrical Engineering from the École Polytech-
´ Canada.
nique, Montreal,
Colin Ashford is the owner of the independent consulting company OSSEvolution.

Colin is a professional engineer with over twenty-five years experience in the com-
puting and telecommunications industry, primarily concerned with the standardiza-
tion of distributed systems and telecommunications networks. He has held senior
positions in Nortel with responsibilities for international standards and project man-
agement. Colin has been an invited speaker at TMF and ECOOP conferences, and
is an OSS Through Java Fellow.
He holds a master’s degree in Computer Science from Carleton University, Ot-
tawa, Canada.
143
Index
<CreateInventoryRecordByValue>, Appmsg.xsd, 112

83 architectural direction, 11
<GetInventoryRecordByKeyRe- architectural pattern, 25, 139
quest>, 56, 78 architectural structure, 137
<GetInventoryRecordByKeyRe- architectural style, 12, 139
sponse>, 78 associative look-up, 19, 64, 95
<appmsg:endOfReply>, 98 atomic execution, 100
<appmsg:records>, 98 attribute population pattern, see Manage-Entity
<appmsg:sequence>, 98 Attribute Population pattern
<appmsg:template>, 52, 98 attribute synchronization, 20
<attributeNames>, 93 attribute values
<binding>, 132 transfer, 91
<endOfReply>, 51
<extension>, 34, 51 bandwidth conservation, 100
<lastUpdateVersionNumber>, 33 BaseEvent, 43
<location>, 69 binary encoding, 17
<message>, 132 binding of patterns, 17
<operation>, 132, 133 BPF, see TM Business Process Framework
<portType>, 132, 133 bulk update pattern, see Managed-Entity Bulk
<record>, 84, 89 Update pattern
<recordKey>, 33 business problem, 5
<sequence>, 51 Business Process Framework, see TM Business
<service>, 132 Process Framework
<template>, 97 business rules, 3
OSS client, 8 call-back address, 16

XML data types, 19 CIM, see Common Information Model
client-server, 2
accessor, 28 client-server style, 3, 14
adaptation and persistence layer, 7 Command pattern, 65
ADDRESS, 32 command-status request pattern, see OSS
alarms, 41 Command–Status pattern
application context, 76, see OSS Application Common Information Model, 13
Context concurrent updating, 104
application layer, 8, see OSS application layer configuration, 139
Application Programming Interface, 17 connectivity resource, 3, 8, 139
ApplicationFaultType, 40 consistency of result, 100
145
146 Index
CONTACTNUMBER, 32 factory pattern, see OSS Factory pattern

CORBA objects, 8 federation, 75
coupling formal query languages, 95
client/server, 16 functional partitioning, 6
Create, Read, Update, Delete model, 20
CreateInventoryRecordByValue, 84, getInventoryRecordByKey, 39, 88, 93
121, 122 getInventoryRecordByKey(), 19, 32,
createInventoryRecordByValue(), 38, 92
38, 126 getInventoryRecordByKeyRe-
createInventoryRecordByValueOp- sponse, 89
eration, 133 getInventoryRecordsByTem-
CreateInventoryRecordByVal- plate(), 38, 50, 97
ueRequestType, 84, 123 getInventoryRecordsByTem-
CREATIONDATE, 31 plateRequest, 51
CRUD, 13, see Create, Read, Updated, Delete getInventoryRecordsByTem-
model plateResponse, 51
Customer Relationship Management, 71, 139 getManagedEntityTypes(), 38
getNext<items>(n), 48, 49
Data Transfer Object pattern, 26 getter, see accessor
Data Transfer Services, 137 glossary, 139
design pattern, 4, 139, see OSS Design Patterns
Digital Subscriber Loop (DSL), 139 ID, 76
discovery pattern, see OSS Discovery pattern implementation profile, 16, 139
Distributed Management Task Force, 23 independent software vendors, 3
information exchange
Element Management System, 8 rules for, 14
Element Management System (EMS), 139 information model, 13, 19, 139
EMS, see Element Management System integration interface, 3, see OSS Interface
end-user application, 139 integration layer, see OSS integration layer
engagement style integration tax, vii
consistent, 13 interface categories, 16
Enterprise Java Beans, 8, 17 interface design, 4
EJB 3.0, 37 interface style, 4, 11
enterprise management, 5 Internet Engineering Task Force, 23
Entities.xsd, 112 introspection, 60
EQUIPMENTTYPE, 31 InventoryRecordValue, 30–32, 83, 107
equipment record, 22 InventoryRecordValueType, 52, 84,
EquipmentRecordValue, 31, 32, 50, 83, 89, 97, 98
97, 107 InventorytRecordValue, 31
EquipmentRecordValueType, 84, 89, invocation overhead, 17
98, 121, 123 iterator, 68
event notification pattern, see OSS Event iterator pattern, see OSS Iterator pattern
Notification pattern IteratorNamedProcedure, 68
event notifications, 14, 72 IteratorRequest, 51
execute(), 38, 72 IteratorResponse, 51
extended equipment record, 22
ExtendedEquipmentRecordValue, 31, Java data types, 17
32, 107 Java Message Service, 17, 19, 43, 46, 140
ExtendedEquipmentRecordValue- Java methods, 17
Type, 98 Java Platform, Enterprise Edition, 17, 140
extension, 54 Java-style API, 17
java.io.Serializable, 29
façade, see OSS Façade JAXB
façade pattern, see OSS Façade pattern to implement a client, 121
Index 147
JEE, see Java Platform, Enterprise Edition example, 81

JMS, see Java Message Service managed-entity delete
example, 81
key, 19 managed-entity key, 76
key lookup, 19 assignment, 76
key pattern, see Managed-Entity Key pattern Managed-Entity Key pattern, 13, 75
Managed-Entity Life Cycle pattern, 80
Last Update-Version-Number pattern, 104 Managed-Entity Model, 13, 19
LastUpdateVersionNumber, 30 Managed-Entity Services, 137
layered functionality, see OSS Reference Managed-Entity Template Filter pattern, 13, 95
Model Managed-Entity Update pattern, 86, 94
learning curve managed-entity value, 86, 91, 140
reducing, 13 used to create a managed entity, 80
life cycle pattern, see Managed-Entity Life Managed-Entity Value pattern, 14, 25, 80, 85
Cycle pattern ManagedEntityValue, 29–31, 107
LOCATION, 31 ManagedEntityValueType, 33
Location, 92 management challenge, 3
location, 68, 93 Management Information Base, 13
locked records, 104 Management Integration System, 2, 7, 140
Long Term Evolution (LTE), 140 management logic, 3
long-lived request, 71 management problem, 12
management requirements, see telecommu-
makeInventoryRecordValue(), 38, 83 nications management requirements,
makeNamedProcedureValue(), 38 12
managed entity, 15, 19, 140 management solution, 3, 140
associative lookup, 19 client-server style, 13
attributes, 19 delivery, 2
updating, 86 deploying, 3
bulk updating of, 100 developing, 3, 11, 26
concurrent updating of, 104 using patterns, 4
creation and deletion of, 80 management solutions
identifying, 19 developing, 13
implementation, 20, 26 management system
key to, 19 deployment, 1
name, 83 overview, 1
reference to, 75 management task, 2
referencing, 19 management-integration application, 3, 13,
selection, 95 140
updating multiple, 100 manual intervention, 71
managed resource, 3, 8, 15, 25, 95, 140 message profile, see OSS Message Profile
life cycle, 80 message-driven bean, 39
management, 19 MessageListener, 43
modelling, 19 messaging, 16
reference to, 75 metadata, 36
state, 95 MIB, see Management Information Base
managed system, 3, 8, 140 monitoring
managed-entity business systems, 41
stale values in, 104 equipment, 41
Managed-Entity Attribute Population pattern, mutators, 28
91
managed-entity attributes NAME, 32
updating, 26 named-procedure pattern, see OSS Named-
Managed-Entity Bulk Update pattern, 100 procedure pattern
managed-entity create NamedProcedure, 67, 68
148 Index
Network Element (NE), 140 OSS Reference Architecture, 12, 14, 141
network latency, 100 OSS Reference Model, 6, 12, 141
notification service, 15, 140 OSS Session Profile, 16, 17, 141
notification signatures, 17, 19 OSS Systems Architecture, 7
notification style, 18 developing, 11
null, 92
NUMBERONHAND, 31 pattern, see design pattern
NumberOnHand, 92 pattern approach, 4
numberOnHand, 93, 101 pattern interactions, see OSS Design Patterns
pattern relationships, see OSS Design Patterns
ObjectMessage, 43 pattern usage, see OSS Design Patterns
onMessage(), 43, 72, 125 performance of interfaces, 16
operation signatures, 16, 17, 19 polling, 41
Operations Support System, 3, 8 polymorphism, 83, 85
Operations Support System (OSS), 140 populated attributes, 80
operator applications, 7 population pattern, see Manage-Entity
operator system, 2, 7, 140 Attribute Population pattern
operator-support application, 7, 13, 140 presentation layer, 6, 7
operator-support layer, 6, 7 procedure call model, 17
OSS, see Operations Support System programming pattern, 141
OSS application, 3, 15, 140 publish-and-subscribe model, 42
operational aspects, 36 publish-and-subscribe style, 3, 14, 18
OSS Application Context, 20
OSS application layer, 7 query mechanism, 14
OSS Application Services, 137 QueryReorderItems, 68, 69
OSS client, 13, 14, 141
OSS Command–Status pattern, 71 rapid development, 13
OSS Design Pattern, 141 read-update model, 86
OSS design pattern, 12 Record Type, 76
OSS Design Patterns, 20 RecordCreateEvent, 43
interactions, 135 RECORDID, 29
relationships, 135 RecordKey, 28–30, 107
usage, 137 RecordKeyType, 33, 123
OSS Discovery pattern, 58 records, 68
OSS Event Notification pattern, 14, 41 RECORDTYPE, 29
use, 73 reference model, 6, see OSS Reference Model
OSS Façade pattern, 36 referencing managed entities, 19
OSS Façade, 14, 141 reliable implementation, 13
OSS Façade pattern, 13 remote operations, 14, 15
OSS Factory pattern, 53, 81 Remote Operations Model, 14, 15
OSS functionality asynchronous mode, 16
discovery, 58 synchronous mode, 16
OSS Implementation Profiles, 14, 16 Remote Procedure Call, 16
OSS Integration Interface, 6, 14 removeInventoryRecordByKey(), 38
OSS integration interface, 141 REORDERLEVEL, 32
OSS integration layer, 7 RPC, see Remote Procedure Call
OSS interfaces
brittle, 16 Service Oriented Architecture, 4
coupling, 16 service providers, 3
performance, 16 service quality, 41
OSS Iterator pattern, 48, 96 service-fulfillment application
OSS Message Profile, 16, 18, 18, 141 example, 11
OSS Named-procedure pattern, 14, 64, 99 service-level agreements, 1
use, 72 session-oriented, 17
Index 149
session-oriented data exchange, 141 technology binding, 15, 21

sessionless data exchange, 141 telecommunications management require-
setInventoryRecordByValue, 39, 40 ments, 5
setInventoryRecordByValue(), 38 telecommunications management system, 142
setInventoryRecordsByValues, 102 overview, 1
setInventoryRecordsByValues(), telecommunications service, 142
38, 101 customers, 1
setter, see mutator growth, 1
SID, see TM Information Framework telecommunications-equipment vendors, 3
Simple Inventory, 22 template, 95
create record, 81 template filter pattern, see Managed-Entity
delete record, 81 Template Filter pattern
interface declarations, 107 TextMessage, 45
interface diagram, 27 thoughts
key structure, 76 final, 105
methods, 38, 111 TM Business Process Framework, 5
operations, 39, 112 TM Information Framework, 13
Toronto, 69
re-order example, 65
type definitions
restoring database, 72
Simple Inventory, 107
retrieving attributes, 91
type hierarchy, 85
update attribute values, 87
type safety, 58
use of bulk update, 100
use of discovery pattern, 59 unPopulate(), 92
use of factory pattern, 55 update pattern, see Managed-Entity Update
use of iterator, 96 pattern
use of key, 76 updating multiple managed entities, 100
XML definitions, 112
software architecture, 13, 141 value pattern, see Managed-Entity Value
stale values, 104 pattern
status, 20 value type, 142
String, 92 passing, 53
supplier record, 22
SUPPLIERNAME, 32 Web Services, 4, 8, 19
SupplierRecordValue, 32, 107
support resource, 3, 141 XML document types, 19
synchronous RPC style, 17 XML Schema, 19, 142
system integrators, 3 use, 107
systems architecture, 7, 13, 141 xsi:type, 47, 52, 84, 89, 98
Colophon
The text of this book was prepared in LATEX using TeXShop on a Macintosh Mac
Pro computer. The Java and XML examples were collaboratively prepared on the
same Mac Pro and a Windows computer both using NetBeans. The example code
was extracted from the NetBeans files with Applescripts that look for specially-
formatted comments and then copy the code into the LATEX source file.
The diagrams were prepared on the Mac Pro using Microsoft PowerPoint and
CS Odessa ConceptDraw. The .pdf outputs of the programs were cropped using
Mac Preview and placed in the appropriate locations for inclusion by TeXShop.
151

OSS Design Patterns A Pattern Approach To The Design of Telecommunications Managemen WWW - Update-Boo

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

OSS Design Patterns A Pattern Approach To The Design of Telecommunications Managemen WWW - Update-Boo

Uploaded by

Copyright:

Available Formats

OSS Design Patterns

A Pattern Approach to the Design of

OSS Design Patterns

ISBN 978-3-642-01395-9 e-ISBN 978-3-642-01396-6

Library of Congress Control Number: Applied for

Typesetting: Data supplied by the authors

Production: Scientific Publishing Services Pvt. Ltd., Chennai, India

Cover Design: eStudio Calamar, Steinen-Broo

Printed in acid-free paper

The management of telecommunications networks and services is one of the most

Ireland, April 2009 Martin J. Creaner

About this Book

Organization of the Book

Aylmer, Quebec and Ottawa, Ontario Pierre Gauthier

1 Managing Telecommunications Services . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2 Designing Management Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

3 OSS Architectural Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

3.8 OSS Command–Status Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

4 OSS Programming Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

A Type Definitions for the Simple Inventory . . . . . . . . . . . . . . . . . . . . . . . . . 107

B Implementing an OSS Client Using JAXB . . . . . . . . . . . . . . . . . . . . . . . . . 121

C Binding the OSS Patterns to Web Services . . . . . . . . . . . . . . . . . . . . . . . . 131

D OSS Design Pattern Interaction and Usage . . . . . . . . . . . . . . . . . . . . . . . . 135

About the Authors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

BPF TM Forum Business Process Framework

The world is disgracefully managed, one hardly knows to whom

Most of what we call management consists of making it difficult

1.1 Telecommunications Management Systems Overview

Telecommunications management systems are almost inevitably geographically dis-

However, there are a number of other advantages to distributed management-

Fig. 1.1 Telecommunications Management Systems Deployment

In Fig. 1.1 we illustrate the main parts of a telecommunications management

1.2 The Management Challenge

A management solution is typically developed by integrating, in an integration ap-

1.3 A Pattern Approach

Our experience in both OSS-applications development and standardization over the

1.4 Telecommunications Management Requirements

Fig. 1.2 The TM Forum Business Process Framework Operations Map

Telecommunications management requirements1 are, at a high level, remarkably

1 Often referred to collectively as the business problem.

1.5 OSS Reference Model

Fig. 1.3 OSS Reference Model

OSS integration layer is responsible for coordinating various OSS applications

1.6 OSS Systems Architecture

As we have noted in Sect. 1.1, telecommunications management systems are well

Fig. 1.4 OSS Systems Architecture

Operator system is a workstation that hosts the implementation of the presenta-

Management Integration System is a server that hosts the implementation of the

The OSS Systems Architecture depicted in Fig. 1.4 is a typical implementation of

I’m very good at integral and differential calculus;

2.1 Developing an OSS Systems Architecture

In Fig. 2.1, we illustrate the process of developing an OSS systems architecture;

1. Developing a reference architecture that sets the architectural direction of the

The OSS Reference Architecture is essentially a mapping of the OSS Reference

Fig. 2.1 Systems Architecture Development Process

Architectural style an abstract description of software components and the pat-

Information model a model of information elements, their inter-relationships, and

2.2 Developing Management Solutions

Systems architectures that deliver management solutions lend themselves well to a

2.3 OSS Reference Architecture

As we saw in Sect. 2.1, a reference architecture is a mapping of a reference model

Fig. 2.2 OSS Reference Architecture