oss design patterns a pattern approach to the design of telecommunications managemen www.update-boo

OSS Design Patterns

A Pattern Approach to the Design ofTelecommunications Management Systems

Colin Ashford and Pierre Gauthier

Colin Ashford and Pierre Gauthier

OSS Design PatternsA Pattern Approach to the Design ofTelecommunications Management Systems

ABC

Colin AshfordOSS Evolutionwww.ossevolution.comE-mail: [email protected]

Pierre GauthierOSS Wavewww.osswave.comE-mail: [email protected]

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 GermanCopyright Law of September 9, 1965, in its current version, and permission for use must alwaysbe 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 doesnot imply, even in the absence of a specific statement, that such names are exempt from the relevantprotective 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

9 8 7 6 5 4 3 2 1

springer.com

In loving memory of Carole and for Jean-Loup—Pierre

For Jo and Leon-Philip—Colin

vii

Foreword

The management of telecommunications networks and services is one of the mostchallenging of software endeavors—partly because of the size and the distributednature 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 challengesby providing a framework for the development of management applications—thosesoftware applications that provide the building blocks for management solutions.The members of the TM Forum have elaborated many parts of NGOSS to make itpractical—including in the area of information modeling, process analysis, and con-tract definition. This book further elaborates NGOSS by examining the challengingarea of interface design.

One of the costs of deploying a new service is the cost of integrating all thenecessary 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 thecapital cost of procuring the management software in the first place.

From their long experience of the design and standardization of managementapplications, the authors have extracted a core set of design patterns for the devel-opment of effective and consistent interfaces to management applications. Adoptingthese patterns across the industry could reduce the learning curve for software de-velopers and allow service providers and systems integrators to rapidly and reliablydeploy management solutions and thereby markedly reduce the integration tax.

In a clear and concise way, the authors not only present the various technicalaspects of each pattern, but also the management context in which the patterns couldbe used. The implementation examples of the patterns in two software technologiesdemonstrate 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 hopeyou enjoy reading it.

Ireland, April 2009 Martin J. CreanerPresident, TM Forum

Preface

About this BookThe explosion of telecommunications services has thrust telecommunications

management into the forefront of the drive for effective service delivery. Onceviewed as a necessary evil, Operations Support Systems (OSSs), and the OSS ap-plications they host, are now seen by service-providers as strategic components intheir 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 fromthe size and heterogeneity of networks; the inherent complexity of communicationstechnologies; and the levels of security and reliability demanded by customers andregulators. Hence, over the last twenty years, software engineers have necessarilyturned 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 errorprone.

In this book, we advocate that the OSS community agree on a set of designpatterns to guide the development of interfaces to OSS applications thereby greatlyreducing the so-called “integration tax” paid by service providers in rolling out anew service.

We offer a proven set of design patterns and best practices for the development ofconsistent and effective interfaces to Operations Support Systems and the manage-ment applications they host. The book is the distillation of many years of experiencein developing and deploying telecommunications management applications.

AudienceThe 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 BookIn the first two chapters of the book, we layout the telecommunications manage-

ment landscape—including the driving forces and typical OSS architectures—andmake the case for a pattern-based approach to the design of OSS interfaces. In thesubsequent 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.

GoalsThe 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 rapiddelivery of effective and reliable management solutions. We support our case byfocussing on a consistent presentation format, discussion of the relevance of eachpattern to telecommunications management, and extensive code examples. We hopethat 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 GauthierApril 2009 Colin Ashford

Acknowledgements

It is both customary, and it gives us great pleasure, to have this opportunity to thankall those who made this book possible. First those who reviewed the various draftsof the book and made so many useful recommendations: Adam Boyle, Eric Dil-lon, Craig Gallen, Philippe Lalande, Tony Richardson, and Mike Kelly. Specialthanks 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 alsodue to Martin Creaner for writing the foreword and for permission to use the TMForum’s Business Process Framework Map. We would also like to thank the teamat Springer, Christoph Baumann and Carmen Wolf, for their editorial support andFrank Holzwarth for his help in cheerfully answering all our question on LATEX.

Despite the combined efforts of all these people, any errors or omissions thatremain are the responsibility of the authors.

xi

Contents

1 Managing Telecommunications Services . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1 Telecommunications Management Systems Overview . . . . . . . . . . . . 11.2 The Management Challenge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 A Pattern Approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.4 Telecommunications Management Requirements . . . . . . . . . . . . . . . . 51.5 OSS Reference Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.6 OSS Systems Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.7 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2 Designing Management Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.1 Developing an OSS Systems Architecture . . . . . . . . . . . . . . . . . . . . . . 112.2 Developing Management Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.3 OSS Reference Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.4 Remote Operations Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.5 The OSS Implementation Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162.6 The Managed-Entity Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.7 OSS Design Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

2.7.1 Documenting OSS Design Patterns . . . . . . . . . . . . . . . . . . . . . 212.8 The Simple Inventory OSS Application . . . . . . . . . . . . . . . . . . . . . . . . 222.9 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

3 OSS Architectural Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253.1 Managed-Entity Value Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253.2 OSS Facade Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363.3 OSS Event Notification Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413.4 OSS Iterator Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483.5 OSS Factory Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533.6 OSS Discovery Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583.7 OSS Named-Procedure Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

xiii

xiv Contents

3.8 OSS Command–Status Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713.9 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

4 OSS Programming Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754.1 Managed-Entity Key Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754.2 Managed-Entity Life Cycle Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . 804.3 Managed-Entity Update Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864.4 Managed-Entity Attribute Population Pattern . . . . . . . . . . . . . . . . . . . 914.5 Managed-Entity Template Filter Pattern . . . . . . . . . . . . . . . . . . . . . . . . 954.6 Managed-Entity Bulk Update Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . 1004.7 Last Update-Version-Number Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . 1044.8 Final Thoughts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

A Type Definitions for the Simple Inventory . . . . . . . . . . . . . . . . . . . . . . . . . 107A.1 OSS Session Profile Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107A.2 OSS Message Profile Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

B Implementing an OSS Client Using JAXB . . . . . . . . . . . . . . . . . . . . . . . . . 121B.1 Create Equipment Record Managed-Entity Example . . . . . . . . . . . . . 121B.2 Message Profile Implementation Software Architecture . . . . . . . . . . . 125B.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 . . . . . . . . . . . . . . . . . . . . . . . . 135D.1 OSS Design Pattern Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135D.2 OSS Design Pattern Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

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

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Colophon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Acronyms

BPF TM Forum Business Process FrameworkCDMA Code Division Multiple AccessCIM Common Information ModelCRM Customer Relationship ManagementCRUD Create Read Update DeleteDMTF Distributed Management Task ForceDSL Digital Subscriber LoopEJB Enterprise Java BeansTM

EMS Element Management SystemGSM Global System for Mobile CommunicationsIETF Internet Engineering Task ForceIPTV IP TelevisionJEE Java Platform, Enterprise EditionTM

JMS Java Message ServiceTM

LTE Long-term EvolutionMIB Management Information BaseNE Network ElementOSS Operations Support SystemPC Personal ComputerRPC Remote Procedure CallSOA Service Oriented ArchitectureUDDI Universal Description Discovery and IntegrationXML eXtended Markup Language

xv

Chapter 1Managing Telecommunications Services

The world is disgracefully managed, one hardly knows to whomto complain.

Ronald Firbank

Most of what we call management consists of making it difficultfor people to get their work done.

Peter Drucker

The growth of telecommunications services over the last twenty years has beendriven by two major innovations: mobility and broadband data. Mobile technologieslike GSM and CDMA have made mobile voice-services ubiquitous in most urbancentres around the world, and the emergence of higher-bandwidth mobile technolo-gies, such as UMTS and LTE, are enabling new services like mobile email, videoto the handset, and web browsing. Similarly broadband data-services like DSL andFiber-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 berapidly deployed, and that service-level agreements be honoured. At the same timefierce competition is putting pressure on prices and customer loyalty. Thus prudentservice 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 modelfor telecommunications management that will form a basis for the patterns that wewill 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 networksthat 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 beadded as required.

• Hosting of OSS applications can be centralized on servers in a few locationswhere the applications can be more easily maintained.

Of course distributed systems come with some disadvantages—mainly the cost ofcommunications; 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 managementdeployment. The main elements are as follows:

Operator systems are workstations that host the user interface and applicationsthat support the human operators in carrying out their management tasks. Operatorsystems 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-integrationapplications.

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 thetelecommunications network and are manageable; examples of managed resourcesinclude connectivity resources, end-user applications, and support resources.

Management-integration applications are software components that coordinatethe functionality of OSS applications to deliver management solutions.

OSS applications are software components that manage a particular aspect of atelecommunications system such as a connectivity resource, an end-user applica-tion, or a support resource; OSS applications implement the management logic andbusiness 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 ormore OSSs in a client-server style. As we will see later, operator systems can alsoengage with OSSs in a publish-and-subscribe style to receive event notifications.

OSS applications typically implement a single management function, and comefrom 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 aspectsof their business.

• Telecommunications-equipment vendors providing vendor- and equipment-specificapplications 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 andthe functionality of OSS applications that addresses a particular management prob-lem; examples include service fulfillment, problem resolution, and provisioning ofnetwork 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, normallyremote, OSS applications through their respective integration interfaces. For exam-ple, a service fulfillment management solution—say to fulfill a customer request forDSL 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 thesolution 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 theresources to be managed, or use the same communications or database technologies.These differences make it more difficult for a systems integrator or service providerto integrate OSS applications into a management solution.

Over the years, a number of industry initiatives to reduce integration costs bymeans of specifying standardized interfaces to OSS applications have been at-tempted. Each has been based on detailed models and the particular implementationtechnologies that were available at the time. Many initiatives have been quite suc-cessful but, given the demanding nature of telecommunications management, therehas been an inevitable trend to re-write the standards using newer (and hopefullybetter) technologies. Initiatives to standardize OSS application interfaces continuetoday with the latest software technology offerings—Web Services and Service Ori-ented Architectures (SOA). Although the technology may change, the core softwareissues of designing effective, consistent interfaces to OSS applications remain.

1.3 A Pattern Approach

Our experience in both OSS-applications development and standardization over thelast twenty-five years, has led us to the conclusion that, given the increasing de-mands made of telecommunications management, the industry must take advantageof newer software technologies as they become mature and, at the same time, makesystems 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-specificinterface design patterns that set an architectural direction for OSS interface de-sign for new software technologies and facilitate systems integration with existingtechnologies.

A design pattern captures, in a technology-neutral manner, the essence of aproven 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 thespecification should be drawn up. To complete the specification, the design patternneeds 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 willform 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, remarkablyconsistent whether the service provider is a small internet service-provider or a largecommon-carrier. The TM Forum[1] has captured these requirements in a processframework called the Business Process Framework (BPF)[2]. The TM Forum BPFclassifies 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. Theprocesses 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 processesthat will form the basis of the OSS Reference Model which we will describe in thenext section.

1.5 OSS Reference Model

In order to better understand a class of system requirements and solutions (in ourcase those of telecommunications management), it is often useful to develop a ref-erence model. A reference model is an accepted functional decomposition based ona 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 asolution.

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 modelshown in Marinescau[3]; the functional partitioning is as follows.

Presentation layer is responsible for all aspects of interfacing with operators suchas network managers, craft technicians, or customer-service representatives.

Operator-support layer is responsible for operator-task workflow and validationof operator input; it delegates all requests for management functionality to either theOSS integration layer or directly to the OSS application layer. Examples of operatortasks 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 applicationsto 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 coordinationby calling on the OSS application layer.

OSS application layer is responsible the OSS-application functionality derivedfrom an analysis of specific management requirements, and provides a consistentview 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 wellsuited to be implemented in a distributed, client-server architectural style. In thissection we will develop a typical systems architecture based on the OSS ReferenceModel. The OSS Systems Architecture (see Fig. 1.4) is the architecture of the systemthat is actually deployed and models the implementation of the various layers of theOSS Reference Model. We will describe the various parts of the architecture in thenext 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 asimple command-line interface or a sophisticated graphical interface. The operator-support layer is implemented by an operator-support application that engages witheither 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 theOSS 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 mightbe implemented by Enterprise Java Beans (EJBs)[4], CORBA objects[5], or WebServices[6].

Operations Support System (OSS) is a server that hosts the implementation ofthe OSS Application layer in the form of one or more specific OSS applications; theapplications might be implemented by Enterprise Java Beans (EJBs)[4], CORBAobjects[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 oneor more connectivity resources or can be systems that host support resources orend-user applications.

Managed resource is a logical or physical asset that provides a service within thetelecommunications network and is manageable; examples of managed resourcesinclude connectivity resources, end-user applications, and support resources.

OSS client is an application that engages with a remote OSS application to accessthe latter’s functionality.

The OSS Systems Architecture depicted in Fig. 1.4 is a typical implementation ofthe OSS Reference Model, but could be modified in various ways, including: OSSapplications 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 developmentof telecommunications management systems and indicated that successful serviceproviders are those that see telecommunications management as a strategic tool toimprove service delivery and not as a necessary evil. We have also introduced twomodels that underpin telecommunications management. In the next chapter, we willtalk about how these models are used in designing the software for managementsolutions.

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 2Designing 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 thisfunctional view into a software architecture that allows us to develop and deployan OSS systems architecture that delivers the management solution. A typical OSSclient (either an operator-support application or a management-integration appli-cation), will implement a management solution by engaging with one or more OSSapplications running on one or more OSSs. For example, a service-fulfillment appli-cation supporting a customer-service agent in fulfilling a customer request for DSLservice might access an inventory application to query availability, a DSL EMSto provision and activate the DSL multiplexer, and a billing application to initiatebilling.

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 concernus for most of this chapter. But first we will review the process of developing anOSS 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 twomain steps:

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

2. developing a software architecture—a specification of the systems architecturethat will address the particular management problem; for example, the service-fulfillment problem.

The OSS Reference Architecture is essentially a mapping of the OSS ReferenceModel 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 ofthis book), a related information model, the OSS Reference Architecture, an imple-mentation profile, and a binding to a particular software technology. The softwarearchitecture is a specification of the systems architecture that will be deployed tosolve 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 modelthat 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 systemsarchitectures are best implemented using client-server and publish-and-subscribearchitectural 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 ofinteraction patterns, granularity of operation, and client-server separation; it is amapping of the OSS Reference Model into the architectural style. We will describethe 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 inpractice; adherence to OSS Design Patterns and to the OSS Reference Architecturehelps 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, andtheir behaviour. The TM Forum’s Information Framework[2] is a comprehensiveinformation model for telecommunications management; others include the DMTFCIM model[3] and various MIBs defined by the IETF[4].

Implementation profile a description of the non-functional aspects of the style ofengagement between an OSS client and an OSS application.

Software architecture the specification of the systems architecture in terms ofprogramming and data elements bound to a particular software technology suchas JEE[5] or .NET[6].

Systems architecture the architecture of the system that is actually deployed; itmay 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 aclient-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-integrationapplications) and the required OSS (server) applications.

Now, in practice, most OSS applications will already exist: equipment supplierswill have delivered EMSs with their transmission and switching equipment and ser-vice providers will have already invested in inventory, trouble ticketing, and billingapplications. So developing a new systems architecture to deliver a management so-lution is largely a question of developing the OSS clients (either the operator-supportapplications or the management-integration applications).

An OSS client may need to engage with a number of OSS applications to addressa particular management problem. Having a consistent engagement style across ap-plications will greatly reduce the learning curve associated with interfacing to eachapplication and help in the rapid development of more reliable implementations.Below we list the criteria that are important in achieving a consistent engagementstyle 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.6and the OSS Facade 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 betweenOSS 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 ina reference architecture that we will use as the basis for discussing the OSS DesignPatterns 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 modelinto software components based on a particular architectural style. The referencearchitecture 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 followingsections:

OSS client an application that engages with a remote OSS application to access thelatter’s functionality employing a client-server style for operations and a publish-and-subscribe style for notifications.

OSS Facade a view, in terms of remote operations, exposed by an OSS applica-tion; applications that present similar styles of facade are more easily integrated,see Sect. 3.2.

2.4 Remote Operations Model 15

Notification service a software component that delivers event reports asynchronouslyto 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 atelecommunications 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 byengaging with a managed entity that the corresponding managed resource is man-aged.

Managed resource a logical or physical asset that provides a service within thetelecommunications 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 suchas 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 aremote application. The remote operations model defines three interactions betweena 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 indicatesan abnormal termination of the remote operation perhaps due to incorrect invocationparameters, 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 theclient blocks until the response or exception is received; or

• an asynchronous mode, based on a messaging model, where the client continuesto execute after making the invocation, but has made arrangements to process theresponse or exception when it arrives, generally by providing a call-back address.

Remote operations are documented in terms of operation signatures: operationsignatures specify the operation name, any calling argument-types and any returnargument-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 importantnon-functional requirements that have to be taken into account. Performance of anintegration interface is a measure of rate of invocation of operations across the in-terface; coupling is a measure of the implementation inter-dependence between theOSS client and the OSS application.

Integration interfaces that are tightly coupled, for example, those where the OSSclient 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 faceof 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 theOSS client and the OSS application have been developed using different softwaretechnologies and are interfaced using, say, XML messages, are likely to exhibitlower performance because of the overhead of processing of the XML. However,OSS applications that are loosely coupled are generally more easily integrated andare less brittle in the face of OSS application changes—OSS clients can often usemessage 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 thatcharacterize the non-functional aspects of the reference architecture. We have foundthese profiles useful in developing interfaces to OSS applications; we call theseprofiles the OSS Session Profile and the OSS Message Profile. The characteristicsof the two profiles are summarized in Table 2.1.

2.5 The OSS Implementation Profiles 17

OSS Implementation ProfilesOSS Session Profile OSS Message Profile

CharacteristicTemporal Session-oriented SessionlessCoupling Tight Loose

Remote Operations Mode Synchronous RPCAsynchronous messageexchange

Encoding Style Binary TextManaged-Entity Value-type Object DocumentInterface Definition Style API Message schemaExample Operation Binding JEE JMS (XML)Notification Style Publish-and-subscribe Publish-and-subscribeExample NotificationBinding

JMS (ObjectMessage) JMS (TextMessage)

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 remoteprocedure 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 theapplication.

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 referencearchitecture to JEE is shown in Fig. 2.4: the facade is implemented by an Enter-prise Java Bean (EJB) session bean, and the notification service is implementedby a Java Message Service (JMS) [7]. Operation and notification signatures andargument types are declared in terms of Java methods and Java data types (i.e. aJava-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 asynchronousstyle: the client sends messages to a message queue and specifies a destinationfor the reply. The message types are documented using a schema. The notificationstyle 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 requestand 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 messageprofile. The binding of the reference architecture is shown in Fig. 2.5: the facadeis implemented by a JMS queue and a message-driven bean, and the notificationservice 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 ofXML document types and XML data types respectively using the XML SchemaLanguage[9]. In Appendix C we discuss a binding of the message profile to WebServices.

2.6 The Managed-Entity Model

The resources that we want to manage, that is the managed resources, may takemany 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 managementsolutions, it is helpful to have a consistent model of the management aspects of man-aged resources. The OSS Reference Architecture models the management aspectsof managed resources as managed entities. Managed entities are abstract softwareentities 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 obtaina reference to the managed entity. The Managed-Entity model allows two types ofreferences, 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 unambiguouslyidentify 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 thatit can be used to uniquely identify a managed entity; for example in the operationgetInventoryRecordByKey() (see the Managed-entity Value pattern example inSect. 3.1, p. 32). The Managed-Entity model does not talk about the structure ofthe key for pragmatic reasons—the structure of the key will probably be closelytied to the mechanism used to identify the related managed resource—for examplea 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 requirementfor managing telecommunications services, references to managed entities basedon 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 ofcommunications equipment. We discuss the form of associative look-up in detail inSect. 4.5.

Both the managed-entity key and the associative look-up mechanisms operatewithin 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 managedentity, the OSS client must first locate the appropriate application context and thenuse 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; andDelete 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 theticket—say “outstanding” or “completed”. The managed entity modelling that trou-ble ticket will have a corresponding attribute, likely named status, to model thefield 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 canalso 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 willcause the creation and deletion of the corresponding trouble ticket in the managedsystem. It is the responsibility of the OSS application to synchronize the attributevalue in the managed entity with the corresponding information in the managedresource.

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 adatabase.

As we noted above, a managed entity is an abstract component, and the referencearchitecture gives us no clue as to the implementation of the managed entity. So howcan we read or update attribute values? The answer is that, for every managed-entitytype, an application developer must define a surrogate—the managed-entity valuetype. A managed-entity value-type is a data item bound to a particular softwaretechnology. 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 capturingsuch 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 asolution 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 isthat, in principle, they can be bound to any new software technology; Web Servicesbeing a case in point (see Appendix C).

By making sure that integration-interface specifications adhere to an agreed setof 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 reducethe 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 dozenpatterns 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 toOSS applications; many are adaptations of patterns commonly found in distributedsystems—patterns such as the Facade Pattern, the Factory Pattern, and the Trans-fer Object Pattern. In order to help readers quickly become comfortable with OSSDesign Patterns, we have adopted a format similar to that used by the Gamma etal.[10]. We will describe each design pattern under the following headings:

Name a succinct encapsulation of the essence of the pattern—it should becomepart of the OSS design vocabulary.

Intent a short statement of the rationale and intent of the pattern and the designproblem 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 patternmight 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 XMLSchema 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 itsname 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; andRecord key a unique key to the record.

The extended equipment record type contains the following fields in addition tothose in the equipment record:

Re-order level the level of inventory triggering re-order; andSupplier 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; andRecord key a unique key to the record.

As we discuss the various patterns, we will introduce example code that an OSSclient might use to create records, delete records, read records, and update recordsin the inventory.

2.9 Summary

In this chapter we have introduced a number of tools to help in the design of OSSsystems 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 dozenimportant 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.8. Web Services, World Wide Web Consortium, http://www.w3.org/2002/ws.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 3OSS Architectural Patterns

The physician can bury his mistakes, but the architectcan only advise his client to plant vines.

Frank Lloyd Wright

In this chapter we will introduce a number of architectural patterns that are usefulin designing the overall structure of OSS integration interfaces; they will set thecontext for programming patterns that we will introduce in the next chapter. Of allthe architectural patterns, the Managed-Entity Value pattern and the OSS Facadepattern are the two most important. The Managed-Entity Value pattern is the patternthat is used by clients to read and update the attributes of managed entities (modelsof the resources to be managed), be they trouble tickets or mobile base stations.The OSS Facade pattern is the fundamental pattern used by clients to engage withOSS applications—it packages the functionality offered by the OSS application andmakes 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 ofmanaged 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 easilyengage with multiple OSS applications, it is important that each application exposea consistent read/update interface model.

Intent

Provide a mechanism to efficiently read and update the attribute values of managedentities.

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 byreading and updating the attributes of managed entities that managed resources aremanaged. To help facilitate the development of management solutions, we need todevise a consistent interface style across all OSS applications to read and update theattribute 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 ofthe attribute values of managed entities. For each managed-entity type, define amanaged-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 requeststhat a managed-entity value, corresponding to the managed entity of interest, betransferred 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 themanaged 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 bysending an updated copy of the managed-entity value to the OSS application (seeFig. 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. Wedeal 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 tofactor 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, andshares 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 orupdating 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 theattribute values are transferred whether they are all needed or not. In the case ofa managed entity that has a large number of attributes, and where only a few arerequired, 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 thetwo 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 SimpleInventory 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 thatcan be transferred between OSS client and OSS application. A client accesses amanaged-entity value by an interface that declares accessors/mutators (getters andsetters) to access the fields of the value object that correspond to the attributes of themanaged 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 moredetails 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 {/*** Constants to identify the fields of

* 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 forall 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 (seeSect. 4.7), to define the names of the fields in the value-object that correspond tothe 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, anddeclares a constant to identify the field. The field in the value object corresponds toan 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 InventoryRecordValueinterface, declares accessors/mutators for the three fields of the value object (EQUIP-MENTTYPE, NUMBERONHAND, and LOCATION), and declares three constants to identifythe three fields. Each field in the value object corresponds to an attribute in theequipment 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 fieldsof the value object (REORDERLEVEL and SUPPLIERNAME), and declares two constantsto identify the two fields. Each field in the value object corresponds to an attributein 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 setSupplierName(String supplierName);

String getSupplierName();

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 thevalue object (NAME, ADDRESS, and CONTACTNUMBER), and declares three constants toidentify the three fields. Each field in the value object corresponds to an attributein the supplier record managed-entity. Using the getInventoryRecordByKey()

method defined in the OSS Facade pattern (see Sect. 3.2), the following snippet ofcode prints out the values of an equipment record in the Simple Inventory using avalue 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 valuesSystem.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 outthe fields in the value object that correspond to attribute values of the equipmentrecord managed-entity. The output might look like this:

Equipment Record Value:Record Id = 42Record Type = EquipmentRecordTypeLastUpdateVersionNumber = 1234RecordCreationDate = 2009 4 1 12h15EquipmentType = LineCardNumberOnHand = 10Location = 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 recordtypes.

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 commonelements <recordKey> and <lastUpdateVersionNumber>:

<complexType name="ManagedEntityValueType"><sequence><element name="recordKey" type="entities:RecordKeyType"></element><element name="lastUpdateNumber" type="xsd:long" minOccurs="0"></element>

Using the <extension> element in XML Schema, we now define a complextype 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 supplierrecord value-types. Each of the elements of the complex types (and those extendedfrom the inventory record value-type) correspond to an attribute of the respectiveinventory 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>


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

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


We finally define four element types as the respective Simple Inventory valuedocument 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 usedin the creation of managed-entities and associative addressing of managed entities.The value pattern is also used to invoke named operations and queries. By arrangingvalue types in type hierarchy, it is possible to exploit the polymorphic features ofsoftware technologies such as Java and XML Schema.


3.2 OSS Facade Pattern

The Managed-Entity model gives an OSS client a consistent view of the attributesof a managed entity and, by extension, the information aspects of the correspondingmanaged resource. It is also important that OSS applications expose a consistentview 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 retrievalof 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, OSSapplications should expose a consistent set of operations.

Solution

Define a canonical set of operations that supports the engagement between an OSSclient and an OSS application and package the operations in a facade. We willadapt the Session Facade pattern[4] to provide such packaging. A facade to sup-port telecommunications management should expose operations to at least:

• Create one or more managed entities given initial values for the attributes (seeSect. 4.2).

• Read the attribute values of one or more managed entities selected by key or bymatching attribute values (see Sect. 4.3).

• Update the attribute values of one or more managed entities selected by key orby 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 Facade Pattern 37

Example

As an example of the OSS Facade pattern, we will develop facades to support theSimple Inventory OSS application (see Sect. 2.8) for each of the profiles usingJEE[2] and JMS[6].


Fig. 3.4 OSS Session Facade Implemented in JEE

In our session profile example, the facade is implemented by means of the EJB 3.0session bean and the remote operations are implemented by RMI (see Fig. 3.4). Theinterface 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.

*/

@Remotepublic interface SimpleInventorySession{

public ManagedEntityValue makeManagedEntityValue(String valueType) throws ApplicationException;

public InventoryRecordValue getInventoryRecordByKey(RecordKey key, String[] attrNames)throws ApplicationException;

public InventoryRecordValueIterator getInventoryRecordsByTemplate(InventoryRecordValue template,String[] attributeNames) throws ApplicationException;

public void setInventoryRecordByValue(InventoryRecordValue value, boolean resyncRequired)throws ApplicationException;

public void setInventoryRecordsByValues(InventoryRecordValue[] recordvos)throws ApplicationException;


public RecordKey createInventoryRecordByValue(InventoryRecordValue value)throws ApplicationException;

public void removeInventoryRecordByKey(RecordKey key)throws ApplicationException;

public String[] getManagedEntityTypes()throws ApplicationException;

public NamedProcedureRequest makeNamedProcedureRequest(String valueType) throws ApplicationException;

public NamedProcedureResponse execute(NamedProcedureRequest namedProcedure)throws ApplicationException;

}

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 methodsin the following sections:

makeInventoryRecordValue() make an inventory record value-object giventhe 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) thatwill return, in value objects, the requested attribute values of the inventory recordmanaged-entities matching the supplied template (see Sect. 4.5).

setInventoryRecordByValue() update the attribute values of an inventoryrecord managed-entity using the fields in the supplied value object (see Sect. 4.3).

setInventoryRecordsByValues() update the attribute values of multipleinventory record managed-entities atomically using the fields in the supplied valueobjects (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 facade (see Sect. . ).

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).

63

3.2 OSS Facade Pattern 39


In our message profile example, the facade is implemented by means of a Java Mes-sage Service (JMS)[6] queue and a message-driven bean (see Fig. 3.5). The clientenqueues a JMS message containing the request document onto the message queuefrom 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-drivenbean encodes the reply or exception it receives from the OSS application into a JMSmessage, and places it on a message queue for return to the client application.

Fig. 3.5 OSS Message Facade Implemented In JMS

To illustrate the use of the OSS Facade pattern in the message profile, we willdefine schema fragments for the two operations getInventoryRecordByKey andsetInventoryRecordByValue. 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"/>


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


<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><element name="record" type="entities:InventoryRecordValueType"/>


<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"/>


The full schema is given in Appendix A.

Summary

The OSS Facade pattern encourages the definition of a consistent set of operationsto 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 solutionwill 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 equipmentmalfunctions, call completions, time-outs, completion of statistics-gathering peri-ods, and transmission degradation. An OSS application will monitor equipmenteither by polling it on a periodic basis or by waiting for the equipment to notifythe application. Notifications that indicate equipment malfunction are referred toas 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-termstatistics, 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 notifyOSS clients of event occurrences.

Motivation

OSS applications need to notify multiple OSS clients about event occurrences atunpredictable times, and OSS clients need to be able to select the types of eventsabout which they are prepared to receive information and the rate at which they areprepared 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 abulletin board), and clients subscribe to receive certain types of event notificationswhen 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 thatrequests 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 willillustrate how an event, the creation of an inventory record managed-entity, notifiedby the Simple Inventory application, might be handled by a Java client.

We first define the BaseEvent and RecordCreateEvent interfaces that will giveaccess 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()

throws ApplicationException;}

/*** 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)throws ApplicationException;

}

We next implement the MessageListener interface and the onMessage() method;the onMessage() method is called when a message arrives at the client. The methodverifies that the message is a notification of the creation of an inventory recordmanaged-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 likethis:

Message Received--->Message type: RecordCreateEvent notificationEvent Time= 2009 3 3 1h37 50sNotification content:

Equipment Record Value:RecordId = 42RecordType = EquipmentRecordTypeLastUpdateVersionNumber = 1234RecordCreationDate = 2009 3 3 1h37 49sEquipmentType = LineCardNumberOnHand = 10Location = 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 beof 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-entitymight look like this:

<appmsg:recordCreateEventNotification

xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’xmlns:entities=’http://xml.netbeans.org/schema/Entities’xmlns:appmsg=’http://xml.netbeans.org/schema/appmsg’xsi:schemaLocation=’http://xml.netbeans.org/schema/Entities file:...http://xml.netbeans.org/schema/appmsg file:...

<appmsg:eventTime>2009-02-20T13:20:00-05:00</appmsg:eventTime><appmsg:inventoryRecordValue xsi:type = "entities:EquipmentRecordValueType"><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></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 ofan 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 OSSclients will want to selectively receive notifications from a number of OSS applica-tions, a publish-and-subscribe model, using a message-based notification service, ispreferred.


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 OSSclient can accommodate in one response. An OSS client therefore needs a consistentway to manage the flow of data that it receives from an OSS application in responseto a request that it has made.

Intent

Provide a mechanism to permit OSS clients to receive an undetermined amount ofdata piecemeal.

Motivation

Some OSS requests, such as query requests and template matching requests, canpotentially 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 bereturned 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 iteratorfrom which the OSS client can iteratively request a small number of values or keysfor processing. Fig. 3.8 shows how the OSS Iterator pattern is used in the case ofa query potentially returning a large number of managed-entity values. The OSSclient prepares a query, sends it to the OSS application, and receives an iterator inresponse. The client then requests the next “n” managed-entity values, receives atmost “n” managed-entity values from the iterator, and extracts the required attributevalues. 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, therequired values or keys have been returned, is an added benefit. The OSS Iteratorpattern is based on the Iterator pattern[5].

In the OSS Session Profile, the iterator is implemented as an object with methodgetNext<items>(n); in the OSS Message Profile, the iterator is implemented byincluding in the request and response documents additional complex types to allowfor multiple responses. We will look at these implementations in more detail in thenext 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 inMontreal.


In the following Java example, the iterator is implemented as a serializable Javaobject with a method getNext<items>(n) to return the next n items. Here is howwe 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 iteratorobject in return.

• Repeatedly requests, from the iterator object, an array of 5 equipment recordvalue-objects at a time and prints the required fields.

• Deletes the iterator.

The client code above executes a getInventoryRecordsByTemplate() requestbut, because the parameter (i.e the template) is of type EquipmentRecordValue,the operation will only match equipment records. We discuss this in more detail inSect. 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"/>


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


The IteratorRequest complex type defined in the above schema fragment in-cludes the element, <n>, to indicate the maximum number of value documents to bereturned in the response. The IteratorResponse complex type definition includestwo 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 bymeans of the XML Schema element <extension>.

The schema fragment for the getInventoryRecordsByTemplateRequest andgetInventoryRecordsByTemplateResponse 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>


<complexType name="GetInventoryRecordsByTemplateResponseType"><complexContent><extension base="appmsg:IteratorResponse"><sequence><element name="records" type="entities:InventoryRecordValueType"maxOccurs="unbounded"/>

<element name="getInventoryRecordsByTemplateRequest"type="appmsg:GetInventoryRecordsByTemplateRequestType"/>

<element name="getInventoryRecordsByTemplateResponse"type="appmsg:GetInventoryRecordsByTemplateResponseType"/>

<element name="getInventoryRecordsByTemplateResponseException"type="appmsg:ApplicationFaultType"/>

To illustrate the use of the OSS Iterator pattern in the message profile, we willuse 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 equipmentrecord value-documents, two at a time, for all equipment records where locationis “Montreal”. The <appmsg:template> element type in the document is derivedfrom the type defined by the schema fragment (i.e. InventoryRecordValueType)by use of the xsi:type attribute indicating that equipment records and extendedequipment records are to be matched.

<appmsg:getInventoryRecordsByTemplateRequest


<appmsg:n>2</appmsg:n><appmsg:template xsi:type = "entities:EquipmentRecordValueType"><entities:location>Montreal</entities:location></appmsg:template></appmsg:getInventoryRecordsByTemplateRequest>

Summary

The OSS Iterator pattern is an important pattern for the practical implementationof OSS integration interfaces: it allows OSS clients to control the rate at whichinformation 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 clientsand OSS applications; examples include the Managed-Entity Life Cycle pattern (seeSect. 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 wouldnormally need to have access to a local copy of the related specification. During thelife cycle of an OSS application, the specifications and implementations of valuetypes may change to accommodate upgrades or patches, and having to distributerevised specifications to OSS clients in a timely manner would be a maintenanceheadache. The solution is to put the responsibility on the OSS client to make orobtain 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 withoutlocal knowledge of the related specification.


Motivation

The primary motivation of the OSS Factory pattern is to reduce the level of couplingbetween an OSS client and an OSS application. For example, if an OSS applicationwere 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 possiblyre-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 andmetadata 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 Facade and managed-entity value-objects are factoriesfor 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 formof XML schemata, from external repositories. The XML Schema types are arrangedin a derivation hierarchy (i.e. by using the extension element in XML Schema), tosupport 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 equipmentrecord value-object.

/** Factory pattern example--make and use a key

*/

EquipmentRecordValue recordvo;RecordKey key;SimpleInventorySession session;


*/session = serviceLocator.getInventorySession();

/** The Simple Inventory session bean is a factory

* for creating Inventory Record value-objects...

*/recordvo = (EquipmentRecordValue) session.makeManagedEntityValue(

"simpleinventory.EquipmentRecordValue");

/* ...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

*/recordvo = (EquipmentRecordValue) session.getInventoryRecordByKey(key,

null);System.out.println(recordvo.toString());

The OSS client first gets a reference to a Simple Inventory session bean. It nextrequests the session bean to make an equipment record value-object, and then usesit to make a record key. The OSS client then populates the key, and requests anequipment record value-object corresponding to the key. Running the above codemight result in the following output:


We saw in Sect. 3.1 that instances of documents in the OSS Message Profile servethe same purpose as Java value objects in the OSS Session Profile. An OSS clientmakes an instance of a document locally using the appropriate schema, and pop-ulates the document as required. This approach requires that the relevant schemabe available to the OSS client. Rather than each client maintaining copies of therelevant schemata, they are stored in, and obtained from, registries. Registries thatstore and make available XML schemata include those defined by UDDI[7] andebXML[8].

The following is the XML Schema for the <GetInventoryRecordByKeyRe-

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







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

<appmsg:getInventoryRecordByKeyRequest

xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’xmlns:appmsg=’http://xml.netbeans.org/schema/appmsg’xmlns:entities=’http://xml.netbeans.org/schema/Entities’xsi:schemaLocation=’http://xml.netbeans.org/schema/appmsg file:...http://xml.netbeans.org/schema/Entities file:...

<appmsg:recordKey><entities:recordId>42</entities:recordId><entities:recordType>EquipmentRecordType</entities:recordType></appmsg:recordKey></appmsg:getInventoryRecordByKeyRequest>

And the response might look like this:

<appmsg:getInventoryRecordByKeyResponse


<appmsg:record xsi:type = "entities:EquipmentRecordValueType"><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></appmsg:record></appmsg:getInventoryRecordByKeyResponse>

Summary

The OSS Factory pattern centralizes either the definition of, or the implementationof, value objects and documents thus reducing administrative issues associated withapplication upgrades and vendor-specific extensions. By arranging the definitions ina 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 clientsmakes it difficult for them to take advantage of newer, or vendor-enhanced, OSSapplications without some sort of modification. We need to provide a mechanism toallow operators to take advantage of updated or vendor-enhanced OSS applicationswithout the need to modify and re-build the OSS client.

Intent

Provide OSS clients with a mechanism to dynamically discover the functionality ofOSS applications.

Motivation

As we have noted, type safety is an important part of software design. One of theways 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 bedetected at compile time or at XML document generation time. However, statically-typed interfaces and schemata imply a tight coupling between OSS client and OSSapplication. 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 todiscover and use the functionality of an OSS application at runtime.

Solution

Require OSS applications and managed-entity values to expose metadata about thefunctionality they offer. Using this metadata, an OSS client can dynamically builda 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 valuemight expose metadata about additional fields in a trouble ticket; a generic operator-support application can present those additional fields to the operator. Or an OSSapplication might expose metadata to enable an operator to discover, and subscribeto, event types supported by an OSS application. Metadata about the following istypically 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 softwaredesigner needs to carefully strike a balance between, on the one hand, type-safetyand 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 patternto develop generic browsers to allow clients to browse the names of the managedentities exposed by the session and message facades and the names and types oftheir attributes.


Since the implementation of managed-entities is hidden, the client must discoverthe information about managed entities from the managed-entity value interface inthe session profile. In the following code, the client first gets a reference to a SimpleInventory session bean, and then discovers, from it, the names of the managed-entitytypes—in this case, the names of the inventory record managed-entity types.


For each inventory record managed-entity type, the client requests the creationof an inventory record managed-entity value-object and, from each, discovers thenames of the respective managed-entity attributes. By introspecting the accessorsof 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-entityattributes.

/*** Example of OSS Discovery pattern use: a generic managed entity browser

*/SimpleInventorySession session;ManagedEntityValue ir1;ServiceLocator serviceLocator = new ServiceLocator();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 facade will look like this:

Managed-entity value-type: ManagedEntityValueAttribute name: RecordKey (simpleinventory.RecordKey)Attribute name: LastUpdateVersionNumber (long)

----------------------------------------------Managed-entity value-type: simpleinventory.InventoryRecordValue

Attribute name: RecordKey (simpleinventory.RecordKey)Attribute name: LastUpdateVersionNumber (long)Attribute name: RecordCreationDate (java.util.Calendar)

----------------------------------------------Managed-entity value-type: simpleinventory.EquipmentRecordValue

Attribute name: RecordKey (simpleinventory.RecordKey)Attribute name: LastUpdateVersionNumber (long)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 entitiesexposed by the message facade and the names and types of their attributes. Since theclient does not know the implementation of the managed-entities, it must discoverthe information about the managed entities from the facade XML schema.

In the code fragment below, the client first gets a reference to the schema and thenparses the schema to build a list of global element specifications that corresponds tothe 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 andtypes of the managed entities exposed by the facade), and iterates over each of thechild element types to discover the names and types (these correspond to the namesand 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 fileFile 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 facade schema will look like this:

Element Name: inventoryRecordKeyElement Type: T=RecordKeyType@http://xml.netbeans.org/schema/EntitiesAttribute Name {http://xml.netbeans.org/schema/Entities}recordIdAttribute Type {http://www.w3.org/2001/XMLSchema}stringAttribute Name {http://xml.netbeans.org/schema/Entities}recordTypeAttribute Type {http://www.w3.org/2001/XMLSchema}string-----------------------------------------------------Element Name: managedEntityValueElement Type: T=ManagedEntityValueType@http://xml.netbeans.org/schema/EntitiesAttribute Name {http://xml.netbeans.org/schema/Entities}recordKeyAttribute Type {http://xml.netbeans.org/schema/Entities}RecordKeyTypeAttribute Name {http://xml.netbeans.org/schema/Entities}lastUpdateNumberAttribute Type {http://www.w3.org/2001/XMLSchema}long-----------------------------------------------------Element Name: inventoryRecordValueElement Type: T=InventoryRecordValueType@http://xml.netbeans.org/schema/EntitiesAttribute Name {http://xml.netbeans.org/schema/Entities}recordKeyAttribute Type {http://xml.netbeans.org/schema/Entities}RecordKeyType


Attribute Name {http://xml.netbeans.org/schema/Entities}lastUpdateNumberAttribute Type {http://www.w3.org/2001/XMLSchema}longAttribute Name {http://xml.netbeans.org/schema/Entities}creationDateAttribute Type {http://www.w3.org/2001/XMLSchema}dateTime-----------------------------------------------------Element Name: equipmentRecordValueElement Type: T=EquipmentRecordValueType@http://xml.netbeans.org/schema/EntitiesAttribute Name {http://xml.netbeans.org/schema/Entities}recordKeyAttribute Type {http://xml.netbeans.org/schema/Entities}RecordKeyTypeAttribute Name {http://xml.netbeans.org/schema/Entities}lastUpdateNumberAttribute Type {http://www.w3.org/2001/XMLSchema}longAttribute Name {http://xml.netbeans.org/schema/Entities}creationDateAttribute Type {http://www.w3.org/2001/XMLSchema}dateTimeAttribute Name {http://xml.netbeans.org/schema/Entities}equipmentTypeAttribute Type {http://www.w3.org/2001/XMLSchema}stringAttribute Name {http://xml.netbeans.org/schema/Entities}numberOnHandAttribute Type {http://www.w3.org/2001/XMLSchema}intAttribute Name {http://xml.netbeans.org/schema/Entities}locationAttribute Type {http://www.w3.org/2001/XMLSchema}string-----------------------------------------------------...

Summary

The OSS Discovery pattern allows developers to strike a balance between typesafety 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 needto 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 supportedby 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 thesubject of complex business or consistency rules that evolve over time. Other tasksmight be complex, but routine, queries that are not amenable to associative look-uptechniques.

Intent

To provide a flexible and extensible method for defining arbitrary procedures andqueries.

Motivation

It is not usual to be able to predict all of the operations that are needed during thedesign of an OSS application; it is often necessary to add operations as applicationsmature and new requirements are identified. If new operations were to be added tothe facade, it would lead to a proliferation of operations and require the repeatedre-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 clientsand is risky from an operational perspective. Allowing operators to invoke complexqueries based on just associative lookup techniques can have consequences in termsof 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 OSSapplications to define value types for the named procedures that OSS clients can ei-ther obtain, or locally instantiate, and populate with the required parameters. Whenan OSS application receives such a value instance, it can validate the parametersand apply any business or consistency rules before carrying out the procedure. Theapplication returns any results as a value type. Fig. 3.12 illustrates the approach.

In addition to centralizing validation, the pattern centralizes the maintenance ofthe 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 alsohelps 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 updatesor vendor-specific extensions to OSS applications without modification. The patternis based on the Command pattern[9].

Example

Using the Simple Inventory application, suppose we want to routinely obtain a listof 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 haveto bring back to the client managed-entity values representing all of the equipmentrecords for the desired location and locally select those where the number-on-handhad dropped below the re-order level—not a pretty solution. A better solution is todo the filtering on the OSS and return only the relevant managed-entity values. Wewill define a named procedure to do just that.


In the OSS Session Profile, and using Java, we first declare the base interfaces forthe 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-objectfrom the session bean, populates with the value “Toronto”, and invokes the query onthe Simple Inventory application. The application responds with an iterator that canbe used to fetch the value objects corresponding to the extended equipment-recordswhere 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

*/SimpleInventorySession session;QueryReorderItemsRequest query;InventoryRecordValueIterator iterator;InventoryRecordValue recordvos[];InventoryRecordValue irvo;/** Get Simple Inventory session bean

*/ServiceLocator serviceLocator = new ServiceLocator();

session = serviceLocator.getInventorySession();

//get a QueryReorderItemsValue objectquery = (QueryReorderItemsRequest) session.makeNamedProcedureRequest(

"simpleinventory.QueryReorderItemsRequest");

//set the location field in the templatequery.setLocation("Toronto");

iterator = (InventoryRecordValueIterator) session.execute(query);

//process 10 equipment record value-objects at a timerecordvos = iterator.getNextInventoryRecords(10);while (recordvos.length > 0) {for (int i = 0; i < recordvos.length; i++) {irvo = recordvos[i];System.out.println(irvo.toString());}recordvos =


The output might look like this:

Equipment Record Value:Equipment type = LineCardNumber on hand = 9Location = TorontoReorder level = 10Supplier Name = Nortel

Equipment Record Value:Equipment type = PowerSupplyNumber on hand = 25Location = TorontoReorder level = 27Supplier Name = Acme

...


As an example of the use of the OSS Named-procedure pattern in the messageprofile, we will use the re-order example in the OSS Session Profile above, notingthat instances of documents in the OSS Message Profile serve the same purpose asJava value objects in the OSS Session Profile (see Sect. 3.1). As an example, andusing XML Schema, we first define the base types, NamedProcedure request andresponse 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 toinclude the iterator request and response element definitions to allow the clientto control the flow of information returned from the OSS application.

<xsd:complexType name="IteratorNamedProcedureRequestType"><xsd:complexContent><xsd:extension base="appmsg:NamedProcedureRequestType"><xsd:sequence><element name="iteratorRequest" type="appmsg:IteratorRequest"/></xsd:sequence></xsd:extension>


<xsd:complexType name="IteratorNamedProcedureResponseType"><xsd:complexContent><xsd:extension base="appmsg:NamedProcedureResponseType"><xsd:sequence><element name="iteratorResponse" type="appmsg:IteratorResponse"/></xsd:sequence></xsd:extension>


<xsd:element name="iteratornamedProcedureRequest"type="appmsg:IteratorNamedProcedureRequestType"/>

<xsd:element name="IteratorNamedProcedureResponse"type="appmsg:IteratorNamedProcedureResponseType"/>

We next define the QueryReorderItems value and response types by extendingthe respective IteratorNamedProcedure types to include the location elementdefinition and the records element definition respectively.

<xsd:complexType name="QueryReorderItemsRequestType"><xsd:complexContent><xsd:extension base="appmsg:IteratorNamedProcedureRequestType"><xsd:sequence><xsd:element name="location" type="xsd:string"/></xsd:sequence></xsd:extension>

<xsd:complexType name="QueryReorderItemsResponseType"><xsd:complexContent><xsd:extension base="appmsg:IteratorNamedProcedureResponseType"><xsd:sequence><xsd:element name="records"type="entities:ExtendedEquipmentRecordValueType"maxOccurs="unbounded"/>



<xsd:element name="queryReorderItemsResponse"type="appmsg:QueryReorderItemsResponseType"/>

<xsd:element name="queryReorderItemsRequest"type="appmsg:QueryReorderItemsRequestType"/>

<xsd:element name="namedProcedureException"type="appmsg:ApplicationFaultType"/>

Using the QueryReorderItems request schema, we next make an instance ofthe query and populate the element <n> with the value 2 (that is requesting at mosttwo extended-equipment record value-documents be returned), and element <loca-tion> with the value “Toronto”.

<appmsg:queryReorderItemsRequest

xmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’xmlns:appmsg=’http://xml.netbeans.org/schema/appmsg’xsi:schemaLocation=’http://xml.netbeans.org/schema/appmsg file:...

<appmsg:iteratorRequest><appmsg:n>2</appmsg:n></appmsg:iteratorRequest><appmsg:location>Toronto</appmsg:location></appmsg:queryReorderItemsRequest>

The first response might look like this:



<appmsg:queryReorderItemsResponsexmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’xmlns:appmsg=’http://xml.netbeans.org/schema/appmsg’xmlns:entities=’http://xml.netbeans.org/schema/Entities’xsi:schemaLocation=’http://xml.netbeans.org/schema/appmsg file:...http://xml.netbeans.org/schema/Entities file:...

<appmsg:iteratorResponse><appmsg:sequence>1</appmsg:sequence><appmsg:endOfReply>false</appmsg:endOfReply></appmsg:iteratorResponse><appmsg:records>


<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>9</entities:numberOnHand><entities:location>Toronto</entities:location><entities:reorderLevel>10</entities:reorderLevel><entities:supplierName>Nortel</entities:supplierName></appmsg:records>

<appmsg:records><entities:recordKey><entities:recordId>4242</entities:recordId><entities:recordType>EquipmentRecordType</entities:recordType>

</entities:recordKey><entities:lastUpdateNumber>5678</entities:lastUpdateNumber><entities:creationDate>2009-04-01T12:19:00-05:00</entities:creationDate><entities:equipmentType>LineCard</entities:equipmentType><entities:numberOnHand>25</entities:numberOnHand><entities:location>Toronto</entities:location><entities:reorderLevel>27</entities:reorderLevel><entities:supplierName>Acme</entities:supplierName></appmsg:records></appmsg:queryReorderItemsResponse>

Summary

The Named-procedure pattern provides an extensible, but strongly-typed, method ofdefining procedures or queries during the lifetime of an OSS application. It is basedon the Command pattern[9] and, like the Command pattern, the value type carriesthe 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 indays. For example, a Customer Relationship Management (CRM) application mightinitiate 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 OSSapplications such as work-order and configuration applications that involve manualintervention. Rather that maintain the session with the client for the duration of thetransaction, the CRM application acknowledges the request and informs the clientof 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 inorder 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 clientneeds to know when a request has been completed and ideally the progress of therequest in the interim.

Solution

The OSS application sends periodic event notifications to inform the OSS client ofthe 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 mightbe used for a long procedure, that of restoring the Simple Inventory database frombackup. The OSS client requests a named-procedure value-type to initiate a restoreof 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, theclient receives progress information in the form of event notifications.


The following code illustrates how the Command–Status pattern might be used inthe session profile. The client requests and populates a restore-from-backup-requestvalue-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.

SimpleInventorySession session;RestoreFromBackupRequest request;RestoreFromBackupResponse response;


*/ServiceLocator serviceLocator = new ServiceLocator();session = serviceLocator.getInventorySession();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 Received--->Message type: RestoreFromBackUpStateEvent notificationEvent Time= 2009 3 3 1h23 14sNotification content: Restore status=STARTED Completion=0%

Message Received--->Message type: RestoreFromBackUpStateEvent notificationEvent Time= 2009 3 3 2h26 19sNotification content: Restore status=INPROGRES Completion=25%



Message Received--->Message type: RestoreFromBackUpStateEvent notificationEvent Time= 2009 3 3 7h23 34sNotification 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 havefound useful in developing interfaces to OSS applications. Some patterns focus onconsistency, some on efficiency, and some balance the need for flexibility with theneed for safety. In the next chapter we will build on these patterns and look at anumber 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.3. XML Schema, World Wide Web Consortium, http://www.w3.org/XML/Schema.4. Facade Pattern, Sun Developer Network,

http://java.sun.com/blueprints/patterns/SessionFacade.html.5. Gamma, E., Helm, R., Johnson, R., Vlissides, J., Design Patterns. Addison-Wesley, Reading,

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.9. Gamma, E., Helm, R., Johnson, R., Vlissides, J., Design Patterns. Addison-Wesley, Reading,

1994, pp. 233–242.

Chapter 4OSS Programming Patterns

To understand is to perceive patterns.Isaiah Berlin

In the previous chapter we introduced a number of architectural patterns; in thischapter we will use them as a foundation to introduce a number of programmingpatterns. Two important patterns are the Managed-Entity Update pattern and theManaged-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 particulartrouble 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 modelledas managed entities so, to refer to a managed resource, an OSS client must actuallyrefer to the managed entity that models the resource. (As we saw in Sect. 2.6, itis the responsibility of the OSS application to maintain the relationship betweenthe managed resource and the managed entity.) Therefore to get an unambiguousreference to a managed resource, we actually need to get an unambiguous referenceto a managed entity.

75

76 4 OSS Programming Patterns

Solution

All managed entities expose a key whose value is unique with respect to the othermanaged 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 ofthe key uniquely identify the managed entity within the application context.

When creating a managed entity, an OSS client can choose to assign the value ofthe key or request that the OSS application assign the value of the key. In either caseit 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 structureof 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, asyou might expect, fairly simple. It is two level structure: a naming context (RecordType) and an identifier (ID) within that context, see Fig. 4.1.


In the following Java example using the OSS Session Profile, the OSS client firstgets a reference to a Simple Inventory session bean. It next requests the sessionbean 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

*/

EquipmentRecordValue recordvo;RecordKey key;SimpleInventorySession session;



/** The Simple Inventory session bean is a factory

* for creating inventory record value-objects...


"simpleinventory.EquipmentRecordValue");

/* ...and the inventory record value-object is a factory for making

* record keys


/** The key is empty, so populate it


/** Try the key



Running the above code might result in the following output:



To use a managed-entity key in the message profile, an OSS client would eitherhave the schema for the key available locally or would obtain it from an externalrepository (see Sect. 3.5).


The following is the XML Schema for the <GetInventoryRecordByKeyRe-

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







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







4.1 Managed-Entity Key Pattern 79


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 responsibilityof the OSS application; the key structure is made available to OSS clients by use ofthe 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 modelthe life cycle of managed resources. Logical resources, such as inventory records,are created and deleted, and physical resources, such as line cards are activated orde-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 managedresources whether those resources be logical resources or physical resources. Weneed to be able to model the creation of logical resources, such as the creation ofa trouble ticket, and the activation of physical resources, such as the activation ofa line card. And, of course, we need to model the reverse: the deletion of a troubleticket and the deactivation of a line card. In the Managed-Entity model, we coulddo this by respectively creating and deleting the managed entities that represent themanaged resources, but the OSS Reference Architecture (see Sect. 2.3) does notprescribe the implementation of managed entities, and that leaves us in a bit of aquandary.

Solution

Use the Managed-Entity Value pattern to create managed entities. A single managedentity is created by populating a managed-entity value with the desired values forthe managed-entity attributes and sending the managed-entity value to the facadeas an argument to a create request (see Fig. 4.2). Attributes corresponding to fieldsnot populated in the managed-entity value are set to default values by the facade.The successful creation of the managed entity indicates the successful creation oractivation of the managed resource.

A single managed entity is deleted by sending a suitably populated key as anargument to a delete request. The successful deletion of the managed entity indicatesthe 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 creationof multiple managed entities with the same attribute values, the creation of mul-tiple managed entities with different attribute values, and the deletion of multiplemanaged 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 anequipment record managed-entity in the Simple Inventory.


In the session profile example below, the OSS client uses the OSS Factory patternto 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, createsthe corresponding record in the inventory. The client then tests the key, and finallydeletes the managed-entity.

/** Equipment Record Life Cycle Example

*/EquipmentRecordValue recordvo, recordvo2;RecordKey key;String[] meTypes;SimpleInventorySession session;




/** 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 thecorresponding equipment record).

7. Request a new equipment record value-object corresponding to the key that wasreturned and print the record values.

8. Delete the equipment record managed-entity using the key (the Simple Inventoryapplication will delete the corresponding equipment record).

Running the above code will result in the following output:

ME TYPE= ManagedEntityValueME TYPE= simpleinventory.InventoryRecordValueME TYPE= simpleinventory.EquipmentRecordValueME TYPE= simpleinventory.ExtendedEquipmentRecordValueME TYPE= simpleinventory.SupplierRecordValue



In the following JMS example using the message profile, the OSS client obtains acopy of the schema for the <CreateInventoryRecordByValue> request element,creates an XML document conforming to the schema, populates it with the desiredvalues, and sends it to the facade message queue.

1 Although the makeInventoryRecordValue() method is declared to return an object oftype InventoryRecordValue, due to the inherent polymorphism of Java, the method is happyto return a sub-type i.e. EquipmentRecordValue; however the client has to cast the return tokeep the compiler happy.

The schema fragments for the CreateInventoryRecordByValue request andresponse types are as follows:

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


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


<element name="createInventoryRecordByValueRequest"type="appmsg:CreateInventoryRecordByValueRequestType"/>

<element name="createInventoryRecordByValueResponse"type="appmsg:CreateInventoryRecordByValueResponseType"/>

<element name="createInventoryRecordByValueResponseException"type="appmsg:ApplicationFaultType"/>

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 anextension of inventory record managed-entity. Hence, in the following document,the client uses the xsi:type attribute in the opening <record> tag to indicate thatthe 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:createInventoryRecordByValueRequestxmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’xmlns:appmsg=’http://xml.netbeans.org/schema/appmsg’xmlns:entities=’http://xml.netbeans.org/schema/Entities’xsi:schemaLocation=’http://xml.netbeans.org/schema/appmsg file:...http://xml.netbeans.org/schema/Entities file:...

<appmsg:record xsi:type = "entities:EquipmentRecordValueType"><entities:recordKey><entities:recordId>42</entities:recordId><entities:recordType>EquipmentRecordType</entities:recordType>

</entities:recordKey><entities:equipmentType>LineCard</entities:equipmentType><entities:numberOnHand>10</entities:numberOnHand><entities:location>Montreal</entities:location></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 thecorresponding equipment record in the inventory:

<appmsg:createInventoryRecordByValueResponse


<appmsg:record><entities:recordId>42</entities:recordId><entities:recordType>EquipmentRecordType</entities:recordType></appmsg:record></appmsg:createInventoryRecordByValueResponse>

Summary

In creating and deleting managed entities, we take advantage of the Managed-EntityValue 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 createand 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 XMLSchema.


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, butreading 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 managedentity 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-entityvalue corresponding to the managed entity in question. The client updates the fieldsof the managed-entity value locally, and then returns the managed-entity value tothe facade with a request to write the new values back to the managed entity and, byextension, to the managed resource. Only attributes that are to be updated need beincluded in the managed-entity value.

Example

OSS Session Profile

Client code, written in Java and using the session profile, to update the attributevalues of a managed entity representing a record in the Simple Inventory might looklike this:

/** Update Equipment Record Managed Entity Example

*/int number, newNumber;SimpleInventorySession session;

/** Get the session bean


/** Get an empty Record Key and populate it

*///key = ...key.setRecordId("42");key.setRecordType("EquipmentRecordType");

/** Get an equipment record value object representing the

* equipment record managed-entity indicated

* by the supplied key and print it



//update value-object copynumber = recordvo.getNumberOnHand();newNumber = number - 1;recordvo.setNumberOnHand(newNumber);

//and write it back to update the equipment record managed-entitysession.setInventoryRecordByValue(recordvo, false);

//Get the recordvo again and print itrecordvo = (EquipmentRecordValue) session.getInventoryRecordByKey(key,



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 theequipment record managed-entity indicated by the supplied key. Having receivedthe equipment record value-object, the client then locally updates the values usingthe equipment record value-object interface. The client finally requests that the up-dated value-object be written back to update the equipment record managed-entityand hence to update the equipment record that the managed entity represents.

The output might look like this:



OSS Message Profile

In the following JMS example, using the message profile, the client populates agetInventoryRecordByKey request document with the appropriate key using theschema fragment shown in Sect. . , p. 78 and enqueues it onto the queue for theSimple Inventory application:




4 1

4.3 Managed-Entity Update Pattern 89

In response, the client receives the following value document corresponding tothe equipment record managed-entity associated with the supplied key:




Note that the schema fragment defining the getInventoryRecordByKeyResponsedocument in Sect. . , p. 78, defines an element named, <record>, of type Inventory-RecordValueType. However, the type of the <record> element returned is actuallyEquipmentRecordValueType, an extension of InventoryRecordValueType; thisis 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 equipmentrecord managed-entity be updated by enqueueing the following document onto theSimple Inventory application queue:

<appmsg:setInventoryRecordByValueRequest


<appmsg:record xsi:type = "entities:EquipmentRecordValueType"><entities:recordKey><entities:recordId>42</entities:recordId><entities:recordType>EquipmentRecordType</entities:recordType></entities:recordKey><entities:lastUpdateNumber>1234</entities:lastUpdateNumber><entities:equipmentType>LineCard</entities:equipmentType><entities:numberOnHand>9</entities:numberOnHand><entities:location>Montreal</entities:location></appmsg:record></appmsg:setInventoryRecordByValueRequest>

14

Finally, the client receives the following response document indicating that theequipment record managed-entity, and the equipment record it represents, have beenupdated.

<appmsg:setInventoryRecordByValueResponse


Summary

In reading and updating the attributes of managed entities, we take advantage of theManaged-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 attributesof 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 managedresources irrespective of their implementation. However, a managed entity may ex-pose a large numbers of attributes, and transferring all of the attribute values in amanaged-entity value, when only a few are required, unnecessarily consumes band-width. This is particularly a problem when OSS clients make queries or selectionsthat result in a large number of managed-entities being returned.

OSS clients need a way of specifying a subset of attribute values to be transferredbetween an OSS client and OSS application.

Intent

To reduce the unnecessary transfer of attribute values between OSS clients and OSSapplications.

Motivation

Managed entities may contain a large number of attributes and client requests mayresult in selecting a large number of managed entities. Transferring all the attributevalues of all of the managed entities either for reading or updating, when only asubset 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 ofall 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 beupdated and to un-populate fields of received managed-entity values. In the sessionprofile, 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 justretrieve the NumberOnHand and Location attributes of the equipment record man-aged entity rather than all of the attributes. We will also un-populate the Locationfield 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 sendinga null as the second parameter to the getInventoryRecordByKey() request, wesend an array of String with two items “NumberOnHand” and “Location”. Beforewe request the update, we will use the unPopulate() method to un-populate theLocation field of the managed-entity value.

/** Update equipment record managed entity

* with Attribute Selection Example

*/EquipmentRecordValue recordvo;RecordKey key;int number, newNumber;SimpleInventorySession session;String[] attributeNames;


*/session = serviceLocator.getInventorySession();/** Make an Inventory Record Value object, use it to make

* a Record Key, and populate the key


"simpleinventory.EquipmentRecordValue");key = recordvo.makeRecordKey();key.setRecordId("42");key.setRecordType("EquipmentRecordType");

/** 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);recordvo = (EquipmentRecordValue) session.getInventoryRecordByKey(key,

attributeNames);

//update local copy of Number on handnumber = recordvo.getNumberOnHand();newNumber = number - 1;recordvo.setNumberOnHand(newNumber);

//unpopulate the Location fieldrecordvo.unPopulate(EquipmentRecordValue.LOCATION);

//and update the equipment record managed-entitysession.setInventoryRecordByValue(recordvo, false);

4.4 Managed-Entity Attribute Population Pattern 93

Message Profile

Below is the amended getInventoryRecordByKey request document that includesan 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:getInventoryRecordByKeyRequest


<appmsg:recordKey><entities:recordId>42</entities:recordId><entities:recordType>EquipmentTypeRecord</entities:recordType></appmsg:recordKey><appmsg:attributeNames><appmsg:item>numberOnHand</appmsg:item><appmsg:item>location</appmsg:item></appmsg:attributeNames></appmsg:getInventoryRecordByKeyRequest>

And the getInventoryRecordByKey response document will look like this:

<appmsg:getInventoryRecordByKeyResponse



</entities:recordKey><entities:lastUpdateNumber>1234</entities:lastUpdateNumber><entities:creationDate>2009-04-01T12:15:00-05:00</entities:creationDate><entities:numberOnHand>10</entities:numberOnHand><entities:location>Montreal</entities:location></appmsg:record></appmsg:getInventoryRecordByKeyResponse>

In the subsequent update of the managed entity, we “un-populate” the attributeby simply not sending it:

<appmsg:setInventoryRecordByValueRequestxmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’xmlns:entities=’http://xml.netbeans.org/schema/Entities’xmlns:appmsg=’http://xml.netbeans.org/schema/appmsg’xsi:schemaLocation=’http://xml.netbeans.org/schema/Entities file:...http://xml.netbeans.org/schema/appmsg file:...



</entities:recordKey><entities:lastUpdateNumber>1234</entities:lastUpdateNumber><entities:numberOnHand>9</entities:numberOnHand></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 tothe client thus conserving bandwidth. It is most useful in reducing the number ofattribute 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 itis useful for a network operator to be able to target operations on resources based ontheir state. For example, a network manager might want to query all line cards thatare currently off-line and start maintenance testing on them, or might want to obtaina 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 bedifficult to implement and intimidating to use.

In the Managed-Entity model (see Sect. 2.6), managed resources are modelled asmanaged entities so OSS clients need a mechanism for selecting managed entitiesbased on their state.

Intent

Provide a simple mechanism for referencing managed entities based on theirattribute-data state.

Motivation

OSS clients need to be able to make ad hoc selections of managed entities basedon the values of their attributes—that is, an associative look-up. Such selectionscan be used to return selected managed-entity values in response to a query, or toselectively 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 applicationto 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 arecomplex 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 allequipment 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 recordsin the Simple Inventory).


Where template selection is used to return value-objects or documents in responseto 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 largenumber, 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 listall of the equipment items on hand in Montreal, so we will use the same examplehere to illustrate the Managed-Entity Template pattern in more detail.


In the following Java example, a managed-entity value-object is used as a templatefor 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

*/SimpleInventorySession session;EquipmentRecordValue template, equipvo;InventoryRecordValue recordvos[];InventoryRecordValueIterator iterator;



/** 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 =


The client code above executes a getInventoryRecordsByTemplate() requestbut, 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 typeInventoryRecordValueType is added the request document to carry the valuesof the attributes to be matched.









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 listof 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 recordswhere the location is “Montreal”. The <appmsg:template> element type in thedocument is derived from the type defined by the schema fragment (i.e. Inventory-RecordValueType) by use of the xsi:type attribute indicating that equipmentrecord managed-entities and extended-equipment record managed entities are to bematched.

<appmsg:getInventoryRecordsByTemplateRequest


<appmsg:n>2</appmsg:n><appmsg:template xsi:type = "entities:EquipmentRecordValueType"><entities:location>Montreal</entities:location></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 sequenceand that the value of the <appmsg:endOfReply> element indicates that there aremore responses to come. The xsi:type attribute in the first <appmsg:records>element indicates that an EquipmentRecordValueType has been returned; thexsi:type attribute in the second <appmsg:records> element indicates that anExtendedEquipmentRecordValueType has been returned. Both are subtypes ofInventoryRecordValueType.



<appmsg:getInventoryRecordsByTemplateResponsexmlns:xsi=’http://www.w3.org/2001/XMLSchema-instance’xmlns:entities=’http://xml.netbeans.org/schema/Entities’xmlns:appmsg=’http://xml.netbeans.org/schema/appmsg’xsi:schemaLocation=’http://xml.netbeans.org/schema/Entities file:...http://xml.netbeans.org/schema/appmsg file:...

<appmsg:sequence>1</appmsg:sequence><appmsg:endOfReply>false</appmsg:endOfReply>

<appmsg:records xsi:type = "entities:EquipmentRecordValueType"><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></appmsg:records>


<appmsg:records xsi:type = "entities:ExtendedEquipmentRecordValueType"><entities:recordKey><entities:recordId>4242</entities:recordId><entities:recordType>EquipmentRecordType</entities:recordType>

</entities:recordKey><entities:lastUpdateNumber>5678</entities:lastUpdateNumber><entities:creationDate>2009-04-01T12:19:00-05:00</entities:creationDate><entities:equipmentType>PowerSupply</entities:equipmentType><entities:numberOnHand>25</entities:numberOnHand><entities:location>Montreal</entities:location><entities:reorderLevel>27</entities:reorderLevel><entities:supplierName>Acme</entities:supplierName></appmsg:records></appmsg:getInventoryRecordsByTemplateResponse>

Summary

The Managed-Entity Template pattern is a simple, but effective, query-by-examplemechanism 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. Forexample:

• the configuration of a piece of network equipment that contains a number ofsub-systems that have to be configured at the same time;

• the updating of multiple entries in inventory or trouble-ticket systems in a mannerthat 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 asmanaged entities so OSS clients need a mechanism to update multiple managedentities 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, orconvenience, it is useful for an OSS client to be able to apply a single update tomultiple 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 onall 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 atomicallybecause if either fails, we will have inconsistencies in the inventory.


The Java client code might look like this (we have ignored error checking for thesake of clarity):

/** Atomic Update of equipment record managed-entity Example

*/int number, newNumber;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 recordnumber = r1vo.getNumberOnHand();newNumber = number - 5;r1vo.setNumberOnHand(newNumber);

// increment number on hand of local copy of Toronto recordnumber = r2vo.getNumberOnHand();newNumber = number + 5;r2vo.setNumberOnHand(newNumber);

//prepare the atomic updateEquipmentRecordValue[] ervos = new EquipmentRecordValue[2];ervos[0] = r1vo;ervos[1] = r2vo;

//and atomically update the equipment record managed-entitiestry {session.setInventoryRecordsByValues(ervos);} catch (ApplicationException e) {//process exception...}

The OSS client obtains managed-entity value-objects corresponding to the managedentities for the Montreal and Toronto records; adjusts the numberOnHand fields ofthe value-objects to reflect the equipment transfer; and requests the managed entitiesbe update atomically with the setInventoryRecordsByValues() operation.

For the message profile, we will use the same example—the atomic update of twoequipment 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"maxOccurs="unbounded"/>


<complexType name="SetInventoryRecordsByValuesResponseType"><sequence/></complexType><element name="setInventoryRecordsByValuesRequest"type="appmsg:SetInventoryRecordsByValuesRequestType"/>

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

<element name="setInventoryRecordsByValuesRequestException"type="appmsg:ApplicationFaultType"/>

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


<appmsg:record xsi:type = "entities:EquipmentRecordValueType"><entities:recordKey><entities:recordId>42</entities:recordId><entities:recordType>EquipmentTypeRecord</entities:recordType>

</entities:recordKey><entities:lastUpdateNumber>1234</entities:lastUpdateNumber><entities:equipmentType>LineCard</entities:equipmentType><entities:numberOnHand>5</entities:numberOnHand><entities:location>Montreal</entities:location>

</appmsg:record><appmsg:record xsi:type = "entities:EquipmentRecordValueType"><entities:recordKey><entities:recordId>4242</entities:recordId><entities:recordType>EquipmentType</entities:recordType>

4.6 Managed-Entity Bulk Update Pattern 103

</entities:recordKey><entities:lastUpdateNumber>5678</entities:lastUpdateNumber><entities:equipmentType>LineCard</entities:equipmentType><entities:numberOnHand>15</entities:numberOnHand><entities:location>Toronto</entities:location></appmsg:record></appmsg:setInventoryRecordsByValuesRequest>

Summary

The Managed-Entity Bulk Update pattern is a convenient way to update a numberof managed entities in one request: it conserves bandwidth and ensures consistencyof updates.


4.7 Last Update-Version-Number Pattern

In a typical telecommunications management network, multiple clients will engagewith the same OSS application to carry out their tasks; for example, a number ofclients could be concurrently updating a trouble-ticket system to indicate progressin managing and correcting a related problem. Having clients concurrently updatethe 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 thefield in her local copy to indicate the trouble has cleared. Client B then updates thetrouble-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 troubleticket in the database, overwrites Client B’s change. This situation becomes morelikely the longer the update cycles; in our case, the longer client A takes enter thenew 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 lockedrecords if the client crashes during the transaction.

Intent

Ensure that attribute values of the managed entities remain consistent in the face ofconcurrent updates.

Motivation

OSS clients request to update the attribute values of managed entities by sendingpopulated managed-entity values to OSS applications. Concurrent updating by mul-tiple clients can cause inconsistencies because of stale values in the managed-entityvalues.

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 numberset when it was populated by the OSS application. This allows the OSS applicationto subsequently detect stale values in a requested update and, in such cases, apply apolicy such as signalling the client. The client could take appropriate action such asrestarting 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 ofinterfaces to OSS applications, and have supported the case with over a dozen designpatterns. We have described the design patterns in a technology-neutral manner, butwe have shown the practicality of the approach by giving examples of how eachcan be implemented by clients using two different software technologies—JEE andJMS. 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 boundto Web Services.

Many of the OSS applications and standards on which we have worked over theyears have successfully used these patterns to make systems integration easier andmore reliable. We believe that were the OSS community to begin to adopt thesepatterns, the integration tax—the cost of integrating OSS applications into OSSsolutions—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 AType 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 Javainterface declarations to define the data and operation types, in the message profilewe use XML Schema[1] to define the data message types. The interface diagram forthe 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 thefacade 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 {

/*** 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();}

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 {/*** Constants to identify the fields of

* 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();

void setSupplierName(String supplierName);

String getSupplierName();}

/*** 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 setSupplierName(String supplierName);

String getSupplierName();

void setSupplierAddress(String supplierAddress);

String getSupplierAddress();

void setContactNumber(String aTelephoneNumber);

String getContactNumber();}

The Java declaration for the OSS Session Facade 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.

*/

@Remotepublic interface SimpleInventorySession{

public ManagedEntityValue makeManagedEntityValue(String valueType) throws ApplicationException;

public InventoryRecordValue getInventoryRecordByKey(RecordKey key, String[] attrNames)throws ApplicationException;

public InventoryRecordValueIterator getInventoryRecordsByTemplate(InventoryRecordValue template,String[] attributeNames) throws ApplicationException;

public void setInventoryRecordByValue(InventoryRecordValue value, boolean resyncRequired)throws ApplicationException;

public void setInventoryRecordsByValues(InventoryRecordValue[] recordvos)throws ApplicationException;

public RecordKey createInventoryRecordByValue(InventoryRecordValue value)throws ApplicationException;

public void removeInventoryRecordByKey(RecordKey key)throws ApplicationException;

public String[] getManagedEntityTypes()throws ApplicationException;

public NamedProcedureRequest makeNamedProcedureRequest(String valueType) throws ApplicationException;

public NamedProcedureResponse execute(NamedProcedureRequest namedProcedure)throws ApplicationException;

}

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()

throws ApplicationException;}

/*** 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)throws ApplicationException;

}

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 elementtypes, and the second, Appmsg.xsd, the message and notification complex-typesand 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">

<!--Define record-key type

A.2 OSS Message Profile Declarations 113

--><complexType name="RecordKeyType"><sequence><element name="recordId" type="string" nillable="false"/><element name="recordType" type="string" nillable="true"/>




<complexType name="InventoryRecordValueType"><complexContent><extension base="entities:ManagedEntityValueType"><sequence><element name="creationDate" type="xsd:dateTime" minOccurs="0"></element></sequence></extension>




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


<complexType name="ExtendedEquipmentRecordValueType">

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


<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"/></schema>

The schema for the message and notification complex-types and element-typesis 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"/>





<element name="createInventoryRecordByValueRequest"

type="appmsg:CreateInventoryRecordByValueRequestType"/><element name="createInventoryRecordByValueResponse"

type="appmsg:CreateInventoryRecordByValueResponseType"/><element name="createInventoryRecordByValueResponseException"

type="appmsg:ApplicationFaultType"/>

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






<element name="getInventoryRecordByKeyResponseException"type="appmsg:ApplicationFaultType"/>

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


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

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

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

<element name="setInventoryRecordByValueRequestException"type="appmsg:ApplicationFaultType"/>

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


<complexType name="SetInventoryRecordsByValuesResponseType"><sequence/></complexType>

<element name="setInventoryRecordsByValuesRequest"

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

<element name="setInventoryRecordsByValuesRequestException"type="appmsg:ApplicationFaultType"/>

<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"type="appmsg:ApplicationFaultType"/>

<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"/>


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


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

<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:complexContent><xsd:extension base="appmsg:NamedProcedureRequestType"><xsd:sequence><element name="iteratorRequest" type="appmsg:IteratorRequest"/></xsd:sequence></xsd:extension>


<xsd:complexType name="IteratorNamedProcedureResponseType">

<xsd:complexContent><xsd:extension base="appmsg:NamedProcedureResponseType"><xsd:sequence><element name="iteratorResponse" type="appmsg:IteratorResponse"/></xsd:sequence></xsd:extension>


<xsd:element name="iteratornamedProcedureRequest"type="appmsg:IteratorNamedProcedureRequestType"/>

<xsd:element name="IteratorNamedProcedureResponse"type="appmsg:IteratorNamedProcedureResponseType"/>

<xsd:complexType name="QueryReorderItemsRequestType"><xsd:complexContent><xsd:extension base="appmsg:IteratorNamedProcedureRequestType"><xsd:sequence><xsd:element name="location" type="xsd:string"/></xsd:sequence></xsd:extension>


<xsd:complexType name="QueryReorderItemsResponseType"><xsd:complexContent><xsd:extension base="appmsg:IteratorNamedProcedureResponseType"><xsd:sequence><xsd:element name="records"type="entities:ExtendedEquipmentRecordValueType"maxOccurs="unbounded"/>



<xsd:element name="queryReorderItemsResponse"type="appmsg:QueryReorderItemsResponseType"/>

<xsd:element name="queryReorderItemsRequest"type="appmsg:QueryReorderItemsRequestType"/>

<xsd:element name="namedProcedureException"type="appmsg:ApplicationFaultType"/>

<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"/>

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



<xsd:element name="recordDeleteEventNotification"type="appmsg:RecordDeleteEventType"/>

</schema>

Appendix BImplementing 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 amessage-driven bean (see Fig. 3.5, p. 39).

For the sake of clarity, we have not shown any supporting code for generatingthe messages, enqueueing the messages, or receiving responses. Within the JEEplatform, 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 OSSclient might create an equipment record managed-entity within the message profileusing Java and the JAXB API. We will also look at the overall implementationarchitecture 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 providesmethods 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 informationis normally obtained by compiling the relevant XML schema into Java classes bythe use of the JAXB binding complier[3].

In the following example, we will show the use of the JAXB API to createan equipment record managed-entity (q.v. Sect. 4.2) in the Simple Inventory. Thefirst step is to compile the relevant XML schemata into Java classes and make theclasses 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 typesand elements:





<element name="createInventoryRecordByValueRequest"type="appmsg:CreateInventoryRecordByValueRequestType"/>

<element name="createInventoryRecordByValueResponse"type="appmsg:CreateInventoryRecordByValueResponseType"/>

<element name="createInventoryRecordByValueResponseException"type="appmsg:ApplicationFaultType"/>

And next, the managed-entity value-types:

<complexType name="RecordKeyType"><sequence><element name="recordId" type="string" nillable="false"/><element name="recordType" type="string" nillable="true"/>




<complexType name="InventoryRecordValueType"><complexContent><extension base="entities:ManagedEntityValueType"><sequence><element name="creationDate" type="xsd:dateTime" minOccurs="0"></element></sequence></extension>

B.1 Create Equipment Record Managed-Entity Example 123



</complexContent></complexType><element name="equipmentRecordValue" type="entities:EquipmentRecordValueType"/>

The following code fragment creates and populates the JAXB equivalents of theCreateInventoryRecordByValueRequestType, the RecordKeyType, and the Equip-mentRecordValueType:

public void createInventoryByValue() throws JMSException {ObjectFactory objFactory = new ObjectFactory();

// Create a JAXB create-inventory-record-by-value request objectCreateInventoryRecordByValueRequestType value = objFactory.

createCreateInventoryRecordByValueRequestType();

// Create a JAXB equipment record object and populate itEquipmentRecordValueType rvalue = new EquipmentRecordValueType();rvalue.setLocation("Montreal");rvalue.setEquipmentType("LineCard");rvalue.setNumberOnHand(new Integer(10));

//Create a RecordKey object and populate itRecordKeyType rkXml = new RecordKeyType();rkXml.setRecordId("42");rkXml.setRecordType("EquipmentRecordType");

// Set the key field of the equipment record objectrvalue.setRecordKey(rkXml);

// Set the equipment record field of the request objectvalue.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 objectstry {marshaller = jaxbContext.createMarshaller();marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);


}

// Write the XML fileStringWriter 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();session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);connection.start();MessageConsumer consumer = session.createConsumer(replyToDestinationQueue);

//Send the message to Simple Inventory queuesendJMSMessageToSimpleInventoryQueue(writer.toString());

//Wait for the reponse on replyToDestinationMessage msg = consumer.receive();System.out.println("Received Message=" + msg.toString());

The request message generated and sent by the client to the message-driven beanwill 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:createInventoryRecordByValueResponsexmlns:ns2="http://xml.netbeans.org/schema/appmsg"xmlns="http://xml.netbeans.org/schema/Entities">

<ns2:record><recordId>42</recordId><recordType>EquipmentRecordType</recordType>

</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 Facade is imple-mented by means of a message-drive bean that intercepts XML messages and makesthe appropriate method calls on the OSS application. Fig. B.1 shows a more detailedsoftware architecture with the session bean and the marshalling and un-marshallingcomponents. 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 SimpleInventory queue as described in Sect B.1.

2. Using an implementation of the onMessage() method, the message-driven beanretrieves the XML message from the queue.

3. Using the JAXB API, the message-driven bean un-marshals the XML messageinto a tree of objects.


4. The message-drive bean builds the createInventoryRecordByValue() methodand calls the session bean.

5. The session bean executes the method on the OSS application and forwards theresponse 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-EntityExample—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();

} catch (JMSException ex) {Logger.getLogger(JMSClient.class.getName()).log(Level.SEVERE, null, ex);

}}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 objectCreateInventoryRecordByValueRequestType value = objFactory.

createCreateInventoryRecordByValueRequestType();

// Create a JAXB equipment record object and populate itEquipmentRecordValueType rvalue = new EquipmentRecordValueType();rvalue.setLocation("Montreal");rvalue.setEquipmentType("LineCard");rvalue.setNumberOnHand(new Integer(10));

//Create a RecordKey object and populate itRecordKeyType rkXml = new RecordKeyType();rkXml.setRecordId("42");rkXml.setRecordType("EquipmentRecordType");

// Set the key field of the equipment record objectrvalue.setRecordKey(rkXml);

// Set the equipment record field of the request objectvalue.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 objectstry {marshaller = jaxbContext.createMarshaller();marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);


}

// Write the XML fileStringWriter 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();session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);connection.start();MessageConsumer consumer = session.createConsumer(replyToDestinationQueue);

//Send the message to Simple Inventory queuesendJMSMessageToSimpleInventoryQueue(writer.toString());

//Wait for the reponse on replyToDestinationMessage msg = consumer.receive();System.out.println("Received Message=" + msg.toString());

} catch (JMSException ex) {Logger.getLogger(JMSClient.class.getName()).log(Level.SEVERE, null, ex);

} 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) {Logger.getLogger(JMSClient.class.getName()).log(Level.SEVERE, null, 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 CBinding the OSS Patterns to Web Services

In describing the two OSS Implementation Profiles (see Sect. 2.5), we chose todescribe 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 todemonstrate the flexibility of our pattern-based approach, we will show how theOSS 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 interoperabilityof heterogeneous applications irrespective of the implementation platform or pro-gramming language. Telecommunications service-providers can take advantage ofthe benefits for both inter- and intra-company application integration. Web Servicesare 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 todescribe the services offered by a Web Service; and

Simple Object Access Protocol (SOAP)[7] a standard packaging structure fortransferring 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 clientand 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 sameexample 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 byre-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, namelycreateInventoryRecordByValueOperation:

<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/literalstyle:

<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 likethis:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" ><soapenv:Header/><soapenv:Body>

<ns2:createInventoryRecordByValueRequestxmlns: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">

134 C Binding the OSS Patterns to Web Services

<recordKey><recordId>42</recordId><recordType>EquipmentRecordType</recordType></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:createInventoryRecordByValueResponsexmlns:ns2="http://xml.netbeans.org/schema/appmsg"xmlns="http://xml.netbeans.org/schema/Entities"><ns2:record><recordId>42</recordId><recordType>EquipmentRecordType</recordType></ns2:record>

</ns2:createInventoryRecordByValueResponse>

</soapenv:Body></soapenv:Envelope>

Appendix DOSS Design Pattern Interaction and Usage

The various patterns that we have introduced in this book do not stand alone: manyare 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 theedges 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-grainedarchitectural structure for an OSS solution. The patterns supporting the Managed-Entity Services allow the fine-grained access to the managed entities. OSS clientswill engage with the OSS Application Services to set up the context of the datatransfers using the patterns supporting the Data Transfer Services.

Fig. D.2 OSS Pattern Usage

References

1. XML Schema, World Wide Web Consortium, http://www.w3.org/XML/Schema.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.4. Web Services, World Wide Web Consortium, http://www.w3.org/2002/ws.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 indeveloping the overall software architecture.

architectural style An abstract description of software components and the patternof 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 includeservice activation, billing, and problem reporting and tracking.

design pattern A description, in a technology-neutral manner, of the essence of aproven and practical solution to a recurring programming or architectural problem.

Digital Subscriber Loop (DSL) A family of technologies that provide digital datatransmission over the wires of a local telephone network.

Element Management System (EMS) A computer system that manages one ormore 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, andtheir behaviour.

139

140 Glossary

Java Platform, Enterprise Edition (JEE)TM An environment for developing anddeploying enterprise applications.

Java Message Service (JMS)TM An API for invoking operations on enterprisemessaging systems.

Long Term Evolution (LTE) The fourth generation mobile broadband standard.

managed entity A model of the management aspects of managed resource; it is byengaging with a managed entity that the corresponding managed resource is man-aged.

managed resource A logical or physical asset that provides a service within thetelecommunications 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 oneor 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 entityand 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; examplesinclude service fulfillment, problem resolution, and the provisioning of network fa-cilities.

management-integration application A software component that coordinates thefunctionality of OSS applications to deliver a management solution.

Network Element (NE) A combination of hardware and software that providesswitching, multiplexing, or transmission services.

notification service A software component that delivers event reports asynchronouslyto OSS clients.

Operations Support System (OSS) A server that hosts OSS applications.

operator system A workstation that hosts the user interface and applications thatsupport 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 atelecommunications system such as a connectivity resource, an end-user service,or a support resource; the OSS application implements the management logic andbusiness rules derived from an analysis of the management requirements.

Glossary 141

OSS client A software component that engages with a remote OSS application toaccess the latters functionality.

OSS Design Pattern A description of an abstract architectural or programmingsolution to telecommunications management problem that has proven successful inpractice.

OSS Facade A view, in terms of remote operations, exposed by an OSS applica-tion.

OSS integration interface The interface at which OSS application functionality ismade 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 ofinteraction patterns, granularity of operation, and client-server separation; it is amapping 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 encounteredwithin the overall framework of the software architecture.

session-oriented data exchange A style of data exchange between a client and aremote 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 remoteapplication 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 ofprogramming and data elements bound to a particular software technology.

support resource An asset that supports the revenue-generating services; supportresources include trouble tickets, alarm reports, and customer and billing records.

systems architecture The architecture of the system that is actually deployed; itmay 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 thatsupervises and manages a telecommunications network and related services.

telecommunications service A service offered by a service provider to customersthat 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 adescription of both a set of operations that a client may request and of state that isaccessible 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, mayalso 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 GauthierFor the last decade Pierre has been involved in the design

and development of software for telecommunications and Operation SupportSystems (OSSs), holding senior positions with Oracle and Nortel. Pierre was thedriving force behind the development of the OSS/J Design Guidelines and is SpecLead for JSR 91, the OSS Trouble Ticket API. Pierre is a JavaOne alumnus,TMFinvited speaker, and JCP Star Spec Lead.

He holds a master’s degree in Electrical Engineering from the Ecole Polytech-nique, Montreal, Canada.

and

training

company

´

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 seniorpositions in Nortel with responsibilities for international standards and project man-agement. Colin has been an invited speaker at TMF and ECOOP conferences, andis an OSS Through Java Fellow.

He holds a master’s degree in Computer Science from Carleton University, Ot-tawa, Canada.

143

.

is the President and CTO of OSS Wave, a software consulting

Index

<CreateInventoryRecordByValue>,83

<GetInventoryRecordByKeyRe-quest>, 56, 78

<GetInventoryRecordByKeyRe-sponse>, 78

<appmsg:endOfReply>, 98<appmsg:records>, 98<appmsg:sequence>, 98<appmsg:template>, 52, 98<attributeNames>, 93<binding>, 132<endOfReply>, 51<extension>, 34, 51<lastUpdateVersionNumber>, 33<location>, 69<message>, 132<operation>, 132, 133<portType>, 132, 133<record>, 84, 89<recordKey>, 33<sequence>, 51<service>, 132<template>, 97

OSS client, 8XML data types, 19

accessor, 28adaptation and persistence layer, 7ADDRESS, 32alarms, 41application context, 76, see OSS Application

Contextapplication layer, 8, see OSS application layerApplication Programming Interface, 17ApplicationFaultType, 40

Appmsg.xsd, 112architectural direction, 11architectural pattern, 25, 139architectural structure, 137architectural style, 12, 139associative look-up, 19, 64, 95atomic execution, 100attribute population pattern, see Manage-Entity

Attribute Population patternattribute synchronization, 20attribute values

transfer, 91

bandwidth conservation, 100BaseEvent, 43binary encoding, 17binding of patterns, 17BPF, see TM Business Process Frameworkbulk update pattern, see Managed-Entity Bulk

Update patternbusiness problem, 5Business Process Framework, see TM Business

Process Frameworkbusiness rules, 3

call-back address, 16CIM, see Common Information Modelclient-server, 2client-server style, 3, 14Command pattern, 65command-status request pattern, see OSS

Command–Status patternCommon Information Model, 13concurrent updating, 104configuration, 139connectivity resource, 3, 8, 139consistency of result, 100

145

146 Index

CONTACTNUMBER, 32CORBA objects, 8coupling

client/server, 16Create, Read, Update, Delete model, 20CreateInventoryRecordByValue, 84,

121, 122createInventoryRecordByValue(),

38, 126createInventoryRecordByValueOp-

eration, 133CreateInventoryRecordByVal-

ueRequestType, 84, 123CREATIONDATE, 31CRUD, 13, see Create, Read, Updated, Delete

modelCustomer Relationship Management, 71, 139

Data Transfer Object pattern, 26Data Transfer Services, 137design pattern, 4, 139, see OSS Design PatternsDigital Subscriber Loop (DSL), 139discovery pattern, see OSS Discovery patternDistributed Management Task Force, 23

Element Management System, 8Element Management System (EMS), 139EMS, see Element Management Systemend-user application, 139engagement style

consistent, 13Enterprise Java Beans, 8, 17

EJB 3.0, 37enterprise management, 5Entities.xsd, 112EQUIPMENTTYPE, 31equipment record, 22EquipmentRecordValue, 31, 32, 50, 83,

97, 107EquipmentRecordValueType, 84, 89,

98, 121, 123event notification pattern, see OSS Event

Notification patternevent notifications, 14, 72execute(), 38, 72extended equipment record, 22ExtendedEquipmentRecordValue, 31,

32, 107ExtendedEquipmentRecordValue-

Type, 98extension, 54

facade, see OSS Facadefacade pattern, see OSS Facade pattern

factory pattern, see OSS Factory patternfederation, 75formal query languages, 95functional partitioning, 6

getInventoryRecordByKey, 39, 88, 93getInventoryRecordByKey(), 19, 32,

38, 92getInventoryRecordByKeyRe-

sponse, 89getInventoryRecordsByTem-

plate(), 38, 50, 97getInventoryRecordsByTem-

plateRequest, 51getInventoryRecordsByTem-

plateResponse, 51getManagedEntityTypes(), 38getNext<items>(n), 48, 49getter, see accessorglossary, 139

ID, 76implementation profile, 16, 139independent software vendors, 3information exchange

rules for, 14information model, 13, 19, 139integration interface, 3, see OSS Interfaceintegration layer, see OSS integration layerintegration tax, viiinterface categories, 16interface design, 4interface style, 4, 11Internet Engineering Task Force, 23introspection, 60InventoryRecordValue, 30–32, 83, 107InventoryRecordValueType, 52, 84,

89, 97, 98InventorytRecordValue, 31invocation overhead, 17iterator, 68iterator pattern, see OSS Iterator patternIteratorNamedProcedure, 68IteratorRequest, 51IteratorResponse, 51

Java data types, 17Java Message Service, 17, 19, 43, 46, 140Java methods, 17Java Platform, Enterprise Edition, 17, 140Java-style API, 17java.io.Serializable, 29JAXB

to implement a client, 121

Index 147

JEE, see Java Platform, Enterprise EditionJMS, see Java Message Service

key, 19key lookup, 19key pattern, see Managed-Entity Key pattern

Last Update-Version-Number pattern, 104LastUpdateVersionNumber, 30layered functionality, see OSS Reference

Modellearning curve

reducing, 13life cycle pattern, see Managed-Entity Life

Cycle patternLOCATION, 31Location, 92location, 68, 93locked records, 104Long Term Evolution (LTE), 140long-lived request, 71

makeInventoryRecordValue(), 38, 83makeNamedProcedureValue(), 38managed entity, 15, 19, 140

associative lookup, 19attributes, 19

updating, 86bulk updating of, 100concurrent updating of, 104creation and deletion of, 80identifying, 19implementation, 20, 26key to, 19name, 83reference to, 75referencing, 19selection, 95updating multiple, 100

managed resource, 3, 8, 15, 25, 95, 140life cycle, 80management, 19modelling, 19reference to, 75state, 95

managed system, 3, 8, 140managed-entity

stale values in, 104Managed-Entity Attribute Population pattern,

91managed-entity attributes

updating, 26Managed-Entity Bulk Update pattern, 100managed-entity create

example, 81managed-entity delete

example, 81managed-entity key, 76

assignment, 76Managed-Entity Key pattern, 13, 75Managed-Entity Life Cycle pattern, 80Managed-Entity Model, 13, 19Managed-Entity Services, 137Managed-Entity Template Filter pattern, 13, 95Managed-Entity Update pattern, 86, 94managed-entity value, 86, 91, 140

used to create a managed entity, 80Managed-Entity Value pattern, 14, 25, 80, 85ManagedEntityValue, 29–31, 107ManagedEntityValueType, 33management challenge, 3Management Information Base, 13Management Integration System, 2, 7, 140management logic, 3management problem, 12management requirements, see telecommu-

nications management requirements,12

management solution, 3, 140client-server style, 13delivery, 2deploying, 3developing, 3, 11, 26using patterns, 4

management solutionsdeveloping, 13

management systemdeployment, 1overview, 1

management task, 2management-integration application, 3, 13,

140manual intervention, 71message profile, see OSS Message Profilemessage-driven bean, 39MessageListener, 43messaging, 16metadata, 36MIB, see Management Information Basemonitoring

business systems, 41equipment, 41

mutators, 28

NAME, 32named-procedure pattern, see OSS Named-

procedure patternNamedProcedure, 67, 68

148 Index

Network Element (NE), 140network latency, 100notification service, 15, 140notification signatures, 17, 19notification style, 18null, 92NUMBERONHAND, 31NumberOnHand, 92numberOnHand, 93, 101

ObjectMessage, 43onMessage(), 43, 72, 125operation signatures, 16, 17, 19Operations Support System, 3, 8Operations Support System (OSS), 140operator applications, 7operator system, 2, 7, 140operator-support application, 7, 13, 140operator-support layer, 6, 7OSS, see Operations Support SystemOSS application, 3, 15, 140

operational aspects, 36OSS Application Context, 20OSS application layer, 7OSS Application Services, 137OSS client, 13, 14, 141OSS Command–Status pattern, 71OSS Design Pattern, 141OSS design pattern, 12OSS Design Patterns, 20

interactions, 135relationships, 135usage, 137

OSS Discovery pattern, 58OSS Event Notification pattern, 14, 41

use, 73OSS Facade pattern, 36OSS Facade, 14, 141OSS Facade pattern, 13OSS Factory pattern, 53, 81OSS functionality

discovery, 58OSS Implementation Profiles, 14, 16OSS Integration Interface, 6, 14OSS integration interface, 141OSS integration layer, 7OSS interfaces

brittle, 16coupling, 16performance, 16

OSS Iterator pattern, 48, 96OSS Message Profile, 16, 18, 18, 141OSS Named-procedure pattern, 14, 64, 99

use, 72

OSS Reference Architecture, 12, 14, 141OSS Reference Model, 6, 12, 141OSS Session Profile, 16, 17, 141OSS Systems Architecture, 7

developing, 11

pattern, see design patternpattern approach, 4pattern interactions, see OSS Design Patternspattern relationships, see OSS Design Patternspattern usage, see OSS Design Patternsperformance of interfaces, 16polling, 41polymorphism, 83, 85populated attributes, 80population pattern, see Manage-Entity

Attribute Population patternpresentation layer, 6, 7procedure call model, 17programming pattern, 141publish-and-subscribe model, 42publish-and-subscribe style, 3, 14, 18

query mechanism, 14QueryReorderItems, 68, 69

rapid development, 13read-update model, 86Record Type, 76RecordCreateEvent, 43RECORDID, 29RecordKey, 28–30, 107RecordKeyType, 33, 123records, 68RECORDTYPE, 29reference model, 6, see OSS Reference Modelreferencing managed entities, 19reliable implementation, 13remote operations, 14, 15Remote Operations Model, 14, 15

asynchronous mode, 16synchronous mode, 16

Remote Procedure Call, 16removeInventoryRecordByKey(), 38REORDERLEVEL, 32RPC, see Remote Procedure Call

Service Oriented Architecture, 4service providers, 3service quality, 41service-fulfillment application

example, 11service-level agreements, 1session-oriented, 17

Index 149

session-oriented data exchange, 141sessionless data exchange, 141setInventoryRecordByValue, 39, 40setInventoryRecordByValue(), 38setInventoryRecordsByValues, 102setInventoryRecordsByValues(),

38, 101setter, see mutatorSID, see TM Information FrameworkSimple Inventory, 22

create record, 81delete record, 81interface declarations, 107interface diagram, 27key structure, 76methods, 38, 111operations, 39, 112re-order example, 65restoring database, 72retrieving attributes, 91update attribute values, 87use of bulk update, 100use of discovery pattern, 59use of factory pattern, 55use of iterator, 96use of key, 76XML definitions, 112

software architecture, 13, 141stale values, 104status, 20String, 92supplier record, 22SUPPLIERNAME, 32SupplierRecordValue, 32, 107support resource, 3, 141synchronous RPC style, 17system integrators, 3systems architecture, 7, 13, 141

technology binding, 15, 21telecommunications management require-

ments, 5telecommunications management system, 142

overview, 1telecommunications service, 142

customers, 1growth, 1

telecommunications-equipment vendors, 3template, 95template filter pattern, see Managed-Entity

Template Filter patternTextMessage, 45thoughts

final, 105TM Business Process Framework, 5TM Information Framework, 13Toronto, 69type definitions

Simple Inventory, 107type hierarchy, 85type safety, 58

unPopulate(), 92update pattern, see Managed-Entity Update

patternupdating multiple managed entities, 100

value pattern, see Managed-Entity Valuepattern

value type, 142passing, 53

Web Services, 4, 8, 19

XML document types, 19XML Schema, 19, 142

use, 107xsi:type, 47, 52, 84, 89, 98

Colophon

The text of this book was prepared in LATEX using TeXShop on a Macintosh MacPro computer. The Java and XML examples were collaboratively prepared on thesame Mac Pro and a Windows computer both using NetBeans. The example codewas 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 andCS Odessa ConceptDraw. The .pdf outputs of the programs were cropped usingMac 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

Documents

management software

management context

software technologies

challenging of software

oss community

oss solutions difcult

dedicated management

necessary applications