OSS Design Patterns: A Pattern Approach to the Design of Telecommunications Management Systems

OSS Design Patterns A Pattern Approach to the Design of Telecommunications Management Systems

Colin Ashford and Pierre Gauthier

OSS Design Patterns A Pattern Approach to the Design of Telecommunications Management Systems

ABC

Colin Ashford OSS Evolution www.ossevolution.com E-mail: [email protected] Pierre Gauthier OSS Wave www.osswave.com E-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 material 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. Duplication of this publication or parts thereof is permitted only under the provisions of the German Copyright Law of September 9, 1965, in its current version, and permission for use must always be obtained from Springer. Violations are liable to prosecution under the German Copyright Law. The use of general descriptive names, registered names, trademarks, etc. in this publication does not imply, even in the absence of a specific statement, that such names are exempt from the relevant protective laws and regulations and therefore free for general use. Typesetting: Data supplied by the authors Production: Scientific Publishing Services Pvt. Ltd., Chennai, India Cover Design: eStudio Calamar, Steinen-Broo Printed in acid-free paper 987654321 springer.com

In loving memory of Carole and for Jean-Loup —Pierre For Jo and Leon-Philip —Colin

Foreword

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

Martin J. Creaner President, TM Forum vii

Preface

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

Audience The primary audience for this book is software engineers and architects who are responsible for the design of telecommunications management systems and for system integrators who are responsible for the development of management solutions. Software development managers and network managers will also find the book useful.

ix

x

Preface

Organization of the Book In the first two chapters of the book, we layout the telecommunications management landscape—including the driving forces and typical OSS architectures—and make the case for a pattern-based approach to the design of OSS interfaces. In the subsequent chapters we describe a number of architectural and programming patterns important to the design of OSS interfaces, and give examples of their implementation using various software development environments.

Goals The main goal of the book is to present a compelling case for the adoption of a core set of design patterns across the OSS community that will help in the rapid delivery of effective and reliable management solutions. We support our case by focussing on a consistent presentation format, discussion of the relevance of each pattern to telecommunications management, and extensive code examples. We hope that the patterns will contribute to the growing ecosystem of best practices and standards, common code, and proven designs for OSS applications and their interfaces.

Aylmer, Quebec and Ottawa, Ontario April 2009

Pierre Gauthier Colin Ashford

Acknowledgements

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

xi

Contents

1

Managing Telecommunications Services . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1 Telecommunications Management Systems Overview . . . . . . . . . . . . 1.2 The Management Challenge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.3 A Pattern Approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.4 Telecommunications Management Requirements . . . . . . . . . . . . . . . . 1.5 OSS Reference Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.6 OSS Systems Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.7 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1 1 3 4 5 6 7 8 9

2

Designing Management Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1 Developing an OSS Systems Architecture . . . . . . . . . . . . . . . . . . . . . . 2.2 Developing Management Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3 OSS Reference Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4 Remote Operations Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.5 The OSS Implementation Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.6 The Managed-Entity Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.7 OSS Design Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.7.1 Documenting OSS Design Patterns . . . . . . . . . . . . . . . . . . . . . 2.8 The Simple Inventory OSS Application . . . . . . . . . . . . . . . . . . . . . . . . 2.9 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11 11 13 14 15 16 19 20 21 22 22 23

3

OSS Architectural Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1 Managed-Entity Value Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 OSS Fac¸ade Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3 OSS Event Notification Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4 OSS Iterator Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5 OSS Factory Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6 OSS Discovery Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7 OSS Named-Procedure Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

25 25 36 41 48 53 58 64 xiii

xiv

Contents

3.8 OSS Command–Status Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 3.9 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 4

OSS Programming Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 4.1 Managed-Entity Key Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 4.2 Managed-Entity Life Cycle Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 4.3 Managed-Entity Update Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 4.4 Managed-Entity Attribute Population Pattern . . . . . . . . . . . . . . . . . . . 91 4.5 Managed-Entity Template Filter Pattern . . . . . . . . . . . . . . . . . . . . . . . . 95 4.6 Managed-Entity Bulk Update Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . 100 4.7 Last Update-Version-Number Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . 104 4.8 Final Thoughts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

A

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

B

Implementing an OSS Client Using JAXB . . . . . . . . . . . . . . . . . . . . . . . . . 121 B.1 Create Equipment Record Managed-Entity Example . . . . . . . . . . . . . 121 B.2 Message Profile Implementation Software Architecture . . . . . . . . . . . 125 B.3 Create Equipment Record Managed-Entity Example—Complete Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

C

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

D

OSS Design Pattern Interaction and Usage . . . . . . . . . . . . . . . . . . . . . . . . 135 D.1 OSS Design Pattern Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 D.2 OSS Design Pattern Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 About the Authors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 Colophon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Acronyms

BPF CDMA CIM CRM CRUD DMTF DSL EJB EMS GSM IETF IPTV JEE JMS LTE MIB NE OSS PC RPC SOA UDDI XML

TM Forum Business Process Framework Code Division Multiple Access Common Information Model Customer Relationship Management Create Read Update Delete Distributed Management Task Force Digital Subscriber Loop Enterprise Java BeansTM Element Management System Global System for Mobile Communications Internet Engineering Task Force IP Television Java Platform, Enterprise EditionTM Java Message ServiceTM Long-term Evolution Management Information Base Network Element Operations Support System Personal Computer Remote Procedure Call Service Oriented Architecture Universal Description Discovery and Integration eXtended Markup Language

xv

Chapter 1

Managing Telecommunications Services

The world is disgracefully managed, one hardly knows to whom to complain. Ronald Firbank Most of what we call management consists of making it difficult for people to get their work done. Peter Drucker

The growth of telecommunications services over the last twenty years has been driven by two major innovations: mobility and broadband data. Mobile technologies like GSM and CDMA have made mobile voice-services ubiquitous in most urban centres around the world, and the emergence of higher-bandwidth mobile technologies, such as UMTS and LTE, are enabling new services like mobile email, video to the handset, and web browsing. Similarly broadband data-services like DSL and Fiber-to-the-Home have enabled new services such as high-speed internet access, audio and video downloading, and IPTV. Using their existing approaches, telecommunications service-providers are having difficulty in managing these new technologies and services. Customers are demanding ever-increasing levels of service: they expect that services, whether fixed or mobile, be always available, that new service offerings be rapidly deployed, and that service-level agreements be honoured. At the same time fierce competition is putting pressure on prices and customer loyalty. Thus prudent service providers are looking to cut costs by managing their networks more efficiently 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 telecommunications management deployment and the challenge that service providers face in managing telecommunications networks. We will go on to develop a reference model for telecommunications management that will form a basis for the patterns that we will discuss in the rest of the book.

1.1 Telecommunications Management Systems Overview Telecommunications management systems are almost inevitably geographically distributed in nature primarily because the resources of telecommunications networks that need to be managed are, themselves, distributed.

1

2

1 Managing Telecommunications Services

However, there are a number of other advantages to distributed managementsystems 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—costeffective PCs to access management applications and large servers or even mainframes to host management applications. • Management systems can grow incrementally—servers and workstations can be added as required. • Hosting of OSS applications can be centralized on servers in a few locations where the applications can be more easily maintained. Of course distributed systems come with some disadvantages—mainly the cost of communications; we will address this issue in later chapters of the book.

Fig. 1.1 Telecommunications Management Systems Deployment

In Fig. 1.1 we illustrate the main parts of a telecommunications management deployment. The main elements are as follows: Operator systems are workstations that host the user interface and applications that support the human operators in carrying out their management tasks. Operator systems connect to remote Management Integration Systems and Operations Support Systems via a network in a client-server arrangement. Management Integration Systems are servers that host management-integration applications.

1.2 The Management Challenge

3

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

1.2 The Management Challenge A management solution is typically developed by integrating, in an integration application or operator-support application, the functionality of a number of, normally remote, OSS applications through their respective integration interfaces. For example, a service fulfillment management solution—say to fulfill a customer request for DSL service—will require engaging a number of OSS applications. These applications might include: an inventory application; an equipment-configuration application; and an order-management application. Developing the management solution

4

1 Managing Telecommunications Services

will likely also require the development of some custom software to implement the solution workflow and logic and to manage any operator interactions required. However, not all OSS applications are built on compatible software and hardware platforms, expose consistent interface styles, expose consistent models of the resources to be managed, or use the same communications or database technologies. These differences make it more difficult for a systems integrator or service provider to integrate OSS applications into a management solution. Over the years, a number of industry initiatives to reduce integration costs by means of specifying standardized interfaces to OSS applications have been attempted. Each has been based on detailed models and the particular implementation technologies that were available at the time. Many initiatives have been quite successful but, given the demanding nature of telecommunications management, there has been an inevitable trend to re-write the standards using newer (and hopefully better) technologies. Initiatives to standardize OSS application interfaces continue today with the latest software technology offerings—Web Services and Service Oriented Architectures (SOA). Although the technology may change, the core software issues of designing effective, consistent interfaces to OSS applications remain.

1.3 A Pattern Approach Our experience in both OSS-applications development and standardization over the last twenty-five years, has led us to the conclusion that, given the increasing demands made of telecommunications management, the industry must take advantage of newer software technologies as they become mature and, at the same time, make systems integration easier. We believe that this can be done by the industry’s coalescing around agreements based on a more abstract style of specification of interfaces to OSS applications. In this book we describe a set of proven, OSS-specific interface design patterns that set an architectural direction for OSS interface design for new software technologies and facilitate systems integration with existing technologies. A design pattern captures, in a technology-neutral manner, the essence of a proven and practical solution to a recurring programming or architectural problem. A design pattern is not a finished software specification, but rather a guide to how the specification should be drawn up. To complete the specification, the design pattern needs to be bound to a particular software technology to be implemented. An agreement on a core set of design patterns to help in the design of OSS interfaces will greatly improve the ability of systems integrators to rapidly develop reliable management solutions whilst having to contend with different software technologies. In the following sections of this chapter, we will introduce two models that will form the basis of our pattern-based approach, but first we will discuss the requirements of managing telecommunications services.

1.4 Telecommunications Management Requirements

5

1.4 Telecommunications Management Requirements

Fig. 1.2 The TM Forum Business Process Framework Operations Map

Telecommunications management requirements1 are, at a high level, remarkably consistent whether the service provider is a small internet service-provider or a large common-carrier. The TM Forum[1] has captured these requirements in a process framework called the Business Process Framework (BPF)[2]. The TM Forum BPF classifies the business processes of a service provider into three major areas, namely: Strategy, infrastructure, and product covering planning and life cycle management of services and infrastructure. Operations covering the core of operational management. Enterprise management covering corporate support management such as financial management, enterprise risk management, and corporate effectiveness management. The relationships between the processes in each area are represented by a map; the map for the Operations area, which will be our focus, is shown in Fig. 1.2. The processes depicted vertically (Operations Support & Readiness, Fulfillment, Assurance, 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.

6

1 Managing Telecommunications Services

Service Management & Operations, Resource Management & Operations, and Supplier/Partner Relationship Management) represent high-level business-related activities. These processes are successively decomposed into more detailed processes that will form the basis of the OSS Reference Model which we will describe in the next section.

1.5 OSS Reference Model In order to better understand a class of system requirements and solutions (in our case those of telecommunications management), it is often useful to develop a reference model. A reference model is an accepted functional decomposition based on a class of requirements; the parts of the model cooperate to meet the requirements. It is an important tool in helping to move from a particular system requirement to a solution.

Fig. 1.3 OSS Reference Model

The OSS Reference Model shown in Fig. 1.3 is a five-layer model that decomposes functional aspects of management solutions. It is based on a layered model shown in Marinescau[3]; the functional partitioning is as follows. Presentation layer is responsible for all aspects of interfacing with operators such as network managers, craft technicians, or customer-service representatives. Operator-support layer is responsible for operator-task workflow and validation of operator input; it delegates all requests for management functionality to either the OSS integration layer or directly to the OSS application layer. Examples of operator tasks are resolving trouble-tickets, simple configuring, and event report alerting.

1.6 OSS Systems Architecture

7

OSS integration layer is responsible for coordinating various OSS applications to realize a management solution and for adapting existing operator applications. Examples of management solutions include problem resolution, end-to-end configuration, and service fulfillment. The OSS integration layer realizes this coordination by calling on the OSS application layer. OSS application layer is responsible the OSS-application functionality derived from an analysis of specific management requirements, and provides a consistent view of the management aspects of managed resources. OSS application functionality includes inventory management, trouble-ticket management, connectivity management, and management of end-user applications. Adaptation and persistence layer is responsible for adapting the managed resources to the view required by the OSS application layer and persisting the management state of the network.

1.6 OSS Systems Architecture As we have noted in Sect. 1.1, telecommunications management systems are well suited to be implemented in a distributed, client-server architectural style. In this section we will develop a typical systems architecture based on the OSS Reference Model. The OSS Systems Architecture (see Fig. 1.4) is the architecture of the system that is actually deployed and models the implementation of the various layers of the OSS Reference Model. We will describe the various parts of the architecture in the next subsections.

Fig. 1.4 OSS Systems Architecture

Operator system is a workstation that hosts the implementation of the presentation and operator-support layers; the presentation layer might be implemented by a simple command-line interface or a sophisticated graphical interface. The operatorsupport layer is implemented by an operator-support application that engages with either an OSS application or with a management integration application. Operator applications can be developed as applets or using traditional programming languages.

8

1 Managing Telecommunications Services

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

1.7 Summary In this chapter we have reviewed some of the forces driving the development of telecommunications management systems and indicated that successful service providers are those that see telecommunications management as a strategic tool to improve service delivery and not as a necessary evil. We have also introduced two models that underpin telecommunications management. In the next chapter, we will talk about how these models are used in designing the software for management solutions.

References

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.

9

Chapter 2

Designing Management Solutions

I’m very good at integral and differential calculus; I know the scientific names of beings animalculous: In short, in matters vegetable, animal, and mineral, I am the very model of a modern Major-General. W. S. Gilbert

The OSS Reference Model we discussed in the previous chapter is a useful functional way of thinking about management solutions; however, we need to turn this functional view into a software architecture that allows us to develop and deploy an OSS systems architecture that delivers the management solution. A typical OSS client (either an operator-support application or a management-integration application), will implement a management solution by engaging with one or more OSS applications running on one or more OSSs. For example, a service-fulfillment application supporting a customer-service agent in fulfilling a customer request for DSL service might access an inventory application to query availability, a DSL EMS to provision and activate the DSL multiplexer, and a billing application to initiate billing. It is the style of the engagement between the OSS client and the OSS application, that is, the style of the interface exposed by the OSS application, that will concern us for most of this chapter. But first we will review the process of developing an OSS systems architecture.

2.1 Developing an OSS Systems Architecture In Fig. 2.1, we illustrate the process of developing an OSS systems architecture; the process is based upon an approach described in Bass et al.[1]. It consists of two main steps: 1. Developing a reference architecture that sets the architectural direction of the systems architecture. 2. developing a software architecture—a specification of the systems architecture that will address the particular management problem; for example, the servicefulfillment problem. The OSS Reference Architecture is essentially a mapping of the OSS Reference Model into software components; the mapping represents a refinement of the archi11

12

2 Designing Management Solutions

tectural style and sets a consistent architectural direction for system implementation. The software architecture is a combination of design patterns (the subject of this book), a related information model, the OSS Reference Architecture, an implementation profile, and a binding to a particular software technology. The software architecture is a specification of the systems architecture that will be deployed to solve the management problem. We will now look at these various items in detail. Management requirements a statement of general telecommunications-management requirements systems must meet. The TMF Business Process Framework Operations Map (see Sect. 1.4), is a key industry source for telecommunications management requirements. OSS Reference Model a functional decomposition that meets telecommunicationmanagement requirements. It is a division of functionality and the data flows between the divisions. The OSS Reference Model, developed in Sect. 1.5, is the model that we shall use as a basis for our discussions.

Fig. 2.1 Systems Architecture Development Process

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

2.2 Developing Management Solutions

13

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

2.2 Developing Management Solutions Systems architectures that deliver management solutions lend themselves well to a client-server style of implementation because of the distributed nature of telecommunications management. To develop a client-server-style OSS systems architecture from scratch would, in principle, require developing the clients to the OSS applications (either the operator-support applications or the management-integration applications) and the required OSS (server) applications. Now, in practice, most OSS applications will already exist: equipment suppliers will have delivered EMSs with their transmission and switching equipment and service providers will have already invested in inventory, trouble ticketing, and billing applications. So developing a new systems architecture to deliver a management solution is largely a question of developing the OSS clients (either the operator-support applications or the management-integration applications). An OSS client may need to engage with a number of OSS applications to address a particular management problem. Having a consistent engagement style across applications will greatly reduce the learning curve associated with interfacing to each application and help in the rapid development of more reliable implementations. Below we list the criteria that are important in achieving a consistent engagement style and the choices that we have found useful: • A consistent model of the resources to be managed (the Managed-Entity Model, see Sect. 2.6). • A consistent style of modifying resource models by clients (CRUD see Sect. 2.6 and the OSS Fac¸ade pattern, see Sect. 3.2). • A consistent style of identifying resource models (Managed-Entity Key pattern, see Sect. 4.1 and Managed-Entity Template Filter pattern, see Sect. 4.5).

14

2 Designing Management Solutions

• A consistent style of information exchange between OSS clients and OSS applications (Remote Operations Model, see Sect. 2.4; Managed-Entity Value pattern, see Sect. 3.1; and OSS Event Notification pattern, see Sect. 3.3). • Consistent rules on the non-functional aspects of information exchange between OSS clients and OSS applications (OSS Implementation Profiles, see Sect. 2.5). • A consistent query mechanism (OSS Named-procedure pattern, see Sect. 3.7). In our experience, meeting these requirements will reduce integration and development time, reduce errors, and reduce training costs. In the next section we will show how many of these criteria can be captured in a reference architecture that we will use as the basis for discussing the OSS Design Patterns in the next chapters of the book.

2.3 OSS Reference Architecture As we saw in Sect. 2.1, a reference architecture is a mapping of a reference model into software components based on a particular architectural style. The reference architecture we have found useful is illustrated in Fig. 2.2.

Fig. 2.2 OSS Reference Architecture

We will discuss each of the parts of the reference architecture in the following sections: OSS client an application that engages with a remote OSS application to access the latter’s functionality employing a client-server style for operations and a publishand-subscribe style for notifications. OSS Fac¸ade a view, in terms of remote operations, exposed by an OSS application; applications that present similar styles of fac¸ade are more easily integrated, see Sect. 3.2.

2.4 Remote Operations Model

15

Notification service a software component that delivers event reports asynchronously to OSS clients. In Sect. 3.3 we will discuss a publish-and-subscribe notification service. OSS application a software component that manages a particular aspect of a telecommunications system such as a connectivity resource, an end-user application, or a support resource. Managed entity a model of the management aspects of managed resource; it is by engaging with a managed entity that the corresponding managed resource is managed. Managed resource a logical or physical asset that provides a service within the telecommunications network and is manageable; examples include connectivity resources, 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 architecture, the reference architecture must be bound to a specific software technology such as JEE[5], JMS[7], Web Services[8], or .NET[6].

2.4 Remote Operations Model The Remote Operations Model models the way a client can invoke operations on a remote application. The remote operations model defines three interactions between a client and a remote application: • a named request, possibly including some calling arguments; • a response, possibly with return arguments, indicating a normal completion; and • one or more named exceptions, possibly including return arguments, indicating an abnormal completion.

Fig. 2.3 Remote Operations

The client invokes a remote operation by sending a request to the application, and then waits for a response or exception to be returned. The exception indicates an abnormal termination of the remote operation perhaps due to incorrect invocation parameters, a failure of the remote host, or a communications failure.

16

2 Designing Management Solutions

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

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

2.5 The OSS Implementation Profiles

17 OSS Implementation Profiles OSS Message Profile OSS Session Profile

Characteristic Temporal Coupling

Session-oriented Tight

Remote Operations Mode

Synchronous RPC

Encoding Style Managed-Entity Value-type Interface Definition Style Example Operation Binding Notification Style Example Notification Binding

Binary Object API JEE Publish-and-subscribe JMS (ObjectMessage)

Sessionless Loose Asynchronous message exchange Text Document Message schema JMS (XML) Publish-and-subscribe 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 interfaces between OSS clients and OSS applications. Remote operations are implemented in a session-oriented, synchronous RPC style. (The client first sets up a session with the OSS application to build a stub to communicate with the application; the client then uses that stub for one or more remote procedure calls.) The remote procedure call types are documented in terms of an Application Programming Interface (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 procedure call model. • Low invocation overhead because the interface is optimized to a particular software technology or platform. • An efficient, binary encoding of the data transfered between the client and the application. However it suffers from a number of disadvantages including that: • Clients are brittle in the face of OSS application changes. • System administrators must make special arrangements for operations to pass through firewalls. • Bridging must be used to support notifications from other OSS applications. We will use Java Platform, Enterprise Edition (JEE)[5] to illustrate the binding of patterns to technology in the session profile. The binding of the reference architecture to JEE is shown in Fig. 2.4: the faca ¸ de is implemented by an Enterprise Java Bean (EJB) session bean, and the notification service is implemented by a Java Message Service (JMS) [7]. Operation and notification signatures and argument types are declared in terms of Java methods and Java data types (i.e. a Java-style API).

18

2 Designing Management Solutions

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 intercompany application integration. Remote operations are realized in an asynchronous style: the client sends messages to a message queue and specifies a destination for the reply. The message types are documented using a schema. The notification style is a publish-and-subscribe style message style; the message types are also documented using a schema. An asynchronous, message-oriented, interface has a number of advantages, including: • The client is not blocked waiting for the OSS application to complete the request and return the result. • The interface is less brittle in the face of changes to OSS applications. • Easier integration because the text-encoding and document-oriented styles. • The receiver (either the OSS client or the OSS application) does not need to be available when the message is sent.

Fig. 2.5 Binding the OSS Message Profile to JMS

However, these advantages come at the expense of a more complicated programming model and processing overhead. We will use JMS to illustrate the binding of patterns to technology in the message profile. The binding of the reference architecture is shown in Fig. 2.5: the faca ¸ de is implemented by a JMS queue and a message-driven bean, and the notification service is implemented by JMS using a JMS topic to publish specific event types.

2.6 The Managed-Entity Model

19

Operation and notification signatures and argument types are specified in terms of XML document types and XML data types respectively using the XML Schema Language[9]. In Appendix C we discuss a binding of the message profile to Web Services.

2.6 The Managed-Entity Model The resources that we want to manage, that is the managed resources, may take many forms, for example: a record in an inventory, a line card in a network element, or a trouble ticket in a trouble ticketing system. In developing management solutions, it is helpful to have a consistent model of the management aspects of managed resources. The OSS Reference Architecture models the management aspects of managed resources as managed entities. Managed entities are abstract software entities that can be uniquely identified and expose a number of named attributes. It is by reading and updating the attributes of the managed entities that the corresponding managed resources are managed. Referencing Managed Entities In order to read or update the attributes of a managed entity, a client must first obtain a reference to the managed entity. The Managed-Entity model allows two types of references, namely: • unambiguous references using a key; and • references using an associative look-up. A managed entity exposes an attribute, a key, that can be used to unambiguously identify it within the context of an OSS application responsible for the managed entity. The Managed-Entity model does not prescribe the structure of the key, only that it can be used to uniquely identify a managed entity; for example in the operation getInventoryRecordByKey() (see the Managed-entity Value pattern example in Sect. 3.1, p. 32). The Managed-Entity model does not talk about the structure of the key for pragmatic reasons—the structure of the key will probably be closely tied to the mechanism used to identify the related managed resource—for example a reference number for a trouble ticket or a hierarchical name for a piece of communications equipment. We discuss managed-entity keys in more detail in Sect. 4.1. Whilst unambiguous references to managed entities are an obvious requirement for managing telecommunications services, references to managed entities based on their state—that is, an associative look-up—are very useful. For example a network manager might want to review all the trouble tickets outstanding for a piece of communications equipment. We discuss the form of associative look-up in detail in Sect. 4.5. Both the managed-entity key and the associative look-up mechanisms operate within the context of an OSS application that is responsible for the managed entity; this context is referred to as the OSS Application Context. To engage with a managed entity, the OSS client must first locate the appropriate application context and then use either a key or an associative look-up to obtain a reference to the particular

20

2 Designing Management Solutions

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 managed entities) by clients is carried out according to a Create, Read, Update, Delete (CRUD) model: Create Read Update Delete

models the creation of managed resources; models the reading of the attributes of managed resources; models the updating of the attributes of managed resources; and models the deletion of managed resources.

For example, a trouble ticket (a managed resource in our reference architecture) might contain an information field named status that denotes the status of the ticket—say “outstanding” or “completed”. The managed entity modelling that trouble ticket will have a corresponding attribute, likely named status, to model the field in the trouble ticket. An OSS client can read the status attribute of the managed entity to get a value corresponding to the status field of the trouble ticket; it can also update the status attribute to update the status field of the trouble ticket. Similarly, the creation and deletion of a managed entity modelling the trouble ticket will cause the creation and deletion of the corresponding trouble ticket in the managed system. It is the responsibility of the OSS application to synchronize the attribute value in the managed entity with the corresponding information in the managed resource. Managed resources may also be managed by the invocation of non-CRUD operations on OSS applications for example, to restart a piece of equipment or reload a database. As we noted above, a managed entity is an abstract component, and the reference architecture gives us no clue as to the implementation of the managed entity. So how can we read or update attribute values? The answer is that, for every managed-entity type, an application developer must define a surrogate—the managed-entity value type. A managed-entity value-type is a data item bound to a particular software technology. We will talk more about managed-entity values in Sect. 3.1.

2.7 OSS Design Patterns Experienced software designers solve commonly-occurring problems by reusing solutions that have proved successful in the past; design patterns are a way of capturing such solutions so that other designers can take advantage of the design experience. We shall use the same approach designing OSS interfaces: capture the essence of a solution in a technology-neutral design pattern.

2.7 OSS Design Patterns

21

To be implemented, a pattern has to be bound to a particular software technology, and we will show examples of bindings to JEE and JMS. The power of patterns is that, in principle, they can be bound to any new software technology; Web Services being a case in point (see Appendix C). By making sure that integration-interface specifications adhere to an agreed set of patterns, the task of integrating OSS applications will be eased: commonlyoccurring problems will be resolved in a common fashion. Whilst this will not ensure integration of OSS applications “out-of-the-box”, it will dramatically reduce the effort required to integrate OSS applications into a management solution.

2.7.1 Documenting OSS Design Patterns In the following chapters of the book, we will discuss a core set of over a dozen patterns that we believe are fundamental to designing consistent OSS application interfaces. These patterns are the distillation of many years of experience in the specification and standardization of OSS applications. They are not necessarily unique to OSS applications; many are adaptations of patterns commonly found in distributed systems—patterns such as the Fac¸ade Pattern, the Factory Pattern, and the Transfer Object Pattern. In order to help readers quickly become comfortable with OSS Design Patterns, we have adopted a format similar to that used by the Gamma et al.[10]. We will describe each design pattern under the following headings: Name a succinct encapsulation of the essence of the pattern—it should become part of the OSS design vocabulary. Intent a short statement of the rationale and intent of the pattern and the design problem it solves. Motivation a description or scenario that illustrates the problem the pattern addresses. Solution a detailed description of the solution to the design problem, either in narrative or graphical form. Example fragments of code or schemata that illustrate how the design pattern might be implemented and used in the context of the two implementation profiles. We will use Java to illustrate the use of patterns in the session profile, and XML Schema grammar and JMS in the message profile.

22

2 Designing Management Solutions

2.8 The Simple Inventory OSS Application To illustrate the patterns, we will use a running example OSS application—the Simple Inventory OSS application. The Simple Inventory application implements (as its name implies) a simple inventory of spare parts, and supports three record types: • an equipment record type; • an extended equipment record type; and • a supplier record type. The equipment record type contains the following fields: Creation date Equipment type Number on hand Location Record key

the date the record was created; a short description of the type of equipment; the number of equipment items on hand; the location of the equipment items; and a unique key to the record.

The extended equipment record type contains the following fields in addition to those in the equipment record: Re-order level Supplier name

the level of inventory triggering re-order; and the name of the preferred equipment supplier.

The supplier record type contains the following fields: Creation date Name Address Contact number Record key

the date the record was created; the name of the supplier; the address of the supplier; a contact telephone number; and a unique key to the record.

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

2.9 Summary In this chapter we have introduced a number of tools to help in the design of OSS systems architectures: the design process, implementation profiles, the OSS Reference Architecture, and the Managed-entity model. This chapter builds on the previous one in setting the context for our pattern approach to the design of OSS interfaces. In the next two chapters of the book, we describe in detail over a dozen important OSS Design Patterns; the text will be accompanied code and schema examples 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 3

OSS Architectural Patterns

The physician can bury his mistakes, but the architect can only advise his client to plant vines. Frank Lloyd Wright

In this chapter we will introduce a number of architectural patterns that are useful in designing the overall structure of OSS integration interfaces; they will set the context for programming patterns that we will introduce in the next chapter. Of all the architectural patterns, the Managed-Entity Value pattern and the OSS Fac¸ade pattern are the two most important. The Managed-Entity Value pattern is the pattern that is used by clients to read and update the attributes of managed entities (models of the resources to be managed), be they trouble tickets or mobile base stations. The OSS Fac¸ade pattern is the fundamental pattern used by clients to engage with OSS applications—it packages the functionality offered by the OSS application and makes it available in a consistent manner.

3.1 Managed-Entity Value Pattern In the OSS Reference Architecture (see Sect. 2.3), the management aspects of managed resources are modelled as managed entities and the information aspects of managed resources are modelled as attributes of the managed entities. It is by reading and updating the values of the attributes of the managed entities, that the corresponding managed resources can be managed. In order for OSS clients to easily engage with multiple OSS applications, it is important that each application expose a consistent read/update interface model.

Intent Provide a mechanism to efficiently read and update the attribute values of managed entities.

25

26

3 OSS Architectural Patterns

Motivation The OSS Reference Architecture does not say how managed entities are to be implemented nor how their attribute values can be read or updated. However, it is by reading and updating the attributes of managed entities that managed resources are managed. To help facilitate the development of management solutions, we need to devise a consistent interface style across all OSS applications to read and update the attribute values of managed entities.

Fig. 3.1 Managed-Entity Value Pattern

Solution Adapt the Data Transfer Object pattern[1] to support the reading and updating of the attribute values of managed entities. For each managed-entity type, define a managed-entity value type, that acts as a surrogate for the managed entity and instances of which can be transferred between the OSS client and the OSS application (see Fig. 3.1). To read and update the attributes of a managed entity, an OSS client requests that a managed-entity value, corresponding to the managed entity of interest, be transferred from the OSS application to the client’s address space. The managedentity value contains a copy, at that point in time, of the attribute values of the managed entity. The client can read and update these copies in its local environment, and subsequently can request that the managed-entity attribute values be updated by sending an updated copy of the managed-entity value to the OSS application (see Fig. 3.2 and Sect. 4.3). An OSS client creates a managed entity by sending a suitably-populated managedentity value to the OSS application with a request to create the managed entity. We deal with the creation (and deletion) of managed entities in detail in Sect. 4.2. It is useful to arrange managed-entity value types in an inheritance hierarchy to factor out common fields and produce a type hierarchy to take advantage of polymorphic operations. We discuss this in more detail in Sect. 4.2.

3.1 Managed-Entity Value Pattern

27

The Managed-Entity Value pattern is based on the Transfer Object pattern, and shares a number of its advantages, including: • It shields the OSS client from the actual implementation of the managed entity. • It offers a consistent mechanism for reading and updating the attributes of a managed entity. • Field-level validation and integrity checking of attribute values can be accomplished in the local environment. • By reading or updating a number of attributes of a managed entity in one go, it reduces the network traffic and delay that would be associated with reading or updating each attribute individually.

Fig. 3.2 Reading the Attribute Values of a Managed Entity Using a Managed-Entity Value

One of the consequences of the Managed-Entity Value pattern is that all of the attribute values are transferred whether they are all needed or not. In the case of a managed entity that has a large number of attributes, and where only a few are required, this can lead to unnecessary consumption of bandwidth and poor response. The Managed-Entity Attribute Population pattern can help alleviate the problem (see Sect. 4.4).

Example In the next sub-sections, we will show how managed-entity values are read in the two OSS profiles. We will use for this, and all the other examples, the Simple Inventory application introduced in Sect. 2.8. The interface diagram for the Simple Inventory value-objects is shown in Fig. 3.3.

28

3 OSS Architectural Patterns

Fig. 3.3 Simple Inventory Value-Object Interface Diagram

OSS Session Profile Example In the OSS Session Profile, a managed-entity value is implemented as an object that can be transferred between OSS client and OSS application. A client accesses a managed-entity value by an interface that declares accessors/mutators (getters and setters) to access the fields of the value object that correspond to the attributes of the managed entity. Using Java, we declare the interfaces shown in Fig. 3.3 as follows. First, the RecordKey interface: /** * * Record-key inteface declaration */ public interface RecordKey extends java.io.Serializable {

3.1 Managed-Entity Value Pattern

29

/** * 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 accessors/mutators for the two fields of the key value-object (RECORDTYPE and RECORDID), and declares two constants to identify the two fields (see Sect. 4.1 for more details of the use of these fields). Next we define the ManagedEntityValue interface—the base interface declaration 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

30

3 OSS Architectural Patterns

*/ public java.util.Hashtable getAttributeValues(String[] names) throws ApplicationException; /** * Get managed-entity attribute names */ public String[] getAttributeNames(); /** * Attribute population methods */ public void unPopulate(String attributeName); public boolean isPopulated(String attributeName); }

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

3.1 Managed-Entity Value Pattern

31

The InventoryRecordValue interface above extends the ManagedEntityValue interface, declares an accessor for the CREATIONDATE field of the value object, and declares a constant to identify the field. The field in the value object corresponds to an attribute in the managed-entity. Next the EquipmentRecordValue interface: /** * Equipment record value-object interface declaration */ public interface EquipmentRecordValue extends InventoryRecordValue { /** * Constants */ public final public final public final

to identify the fields of the equipment record value-object static String EQUIPMENTTYPE = "EquipmentType"; static String NUMBERONHAND = "NumberOnHand"; static String LOCATION = "Location";

/* * Accessors and mutators for the fields of the value-object */ void setEquipmentType(String equipmentType); String getEquipmentType(); void setNumberOnHand(int numberOnHand); int getNumberOnHand(); void setLocation(String aLocation); String getLocation(); }

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

32

3 OSS Architectural Patterns

The ExtendedEquipmentRecordValue interface above extends the EquipmentRecordValue interface, declares accessors/mutators for the two additional fields of the value object (REORDERLEVEL and SUPPLIERNAME), and declares two constants to identify the two fields. Each field in the value object corresponds to an attribute in the extended equipment record managed-entity. And, finally, the SupplierRecordValue interface: /** * Supplier record value object interface */ public interface SupplierRecordValue extends InventoryRecordValue { /** * Constants */ public final public final public final

to identify the fields of the supplier record value-object static String NAME = "SupplierName"; static String ADDRESS = "SupplierAddress"; 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 InventoryRecordValue interface, declares accessors/mutators for the three additional fields of the value object (NAME, ADDRESS, and CONTACTNUMBER), and declares three constants to identify the three fields. Each field in the value object corresponds to an attribute in the supplier record managed-entity. Using the getInventoryRecordByKey() method defined in the OSS Fac¸ade pattern (see Sect. 3.2), the following snippet of code prints out the values of an equipment record in the Simple Inventory using a value object: /* * Print equipment record */ /* * session = ... get a Simple Inventory session bean * key = ... set the key to a previously-saved value and * get the equipment record value-object identified by the key */

3.1 Managed-Entity Value Pattern

33

recordvo = (EquipmentRecordValue) session.getInventoryRecordByKey(key, null); // Print the values System.out.println(recordvo.toString());

With a previously-saved key value, the client requests an equipment record valueobject from the session bean corresponding to the supplied key, and then prints out the fields in the value object that correspond to attribute values of the equipment record managed-entity. The output might look like this: Equipment Record Value: Record Id = 42 Record Type = EquipmentRecordType LastUpdateVersionNumber = 1234 RecordCreationDate = 2009 4 1 12h15 EquipmentType = LineCard NumberOnHand = 10 Location = Montreal

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

We now define the base ManagedEntityValueType to factor out the common elements and :

34

3 OSS Architectural Patterns

Using the element in XML Schema, we now define a complex type for the inventory record value-type:

Again, using the element in XML Schema, we now define complex types for the equipment record, extended-equipment record, and supplier record value-types. Each of the elements of the complex types (and those extended from the inventory record value-type) correspond to an attribute of the respective inventory record managed-entity.



3.1 Managed-Entity Value Pattern

35



We finally define four element types as the respective Simple Inventory value document types.

An instance of a equipment record value document might look like this:

40

3 OSS Architectural Patterns

The following schema fragment defines the setInventoryRecordByValue request and response types and elements:

The following schema fragment defines the ApplicationFaultType type and element:

The full schema is given in Appendix A.

Summary The OSS Fac¸ade pattern encourages the definition of a consistent set of operations to be exposed by all OSS applications. By defining such a set, the learning curve associated with integrating a number of OSS applications into a management solution will be reduced.

3.3 OSS Event Notification Pattern

41

3.3 OSS Event Notification Pattern In modern telecommunications systems, the performance of transmission and switching equipment is closely monitored by OSS applications to ensure service quality. OSS applications monitor equipment for asynchronous events such as equipment malfunctions, call completions, time-outs, completion of statistics-gathering periods, and transmission degradation. An OSS application will monitor equipment either by polling it on a periodic basis or by waiting for the equipment to notify the application. Notifications that indicate equipment malfunction are referred to as alarms. OSS applications also monitor events in business systems, such as order management systems, to determine progress. A CRM application can determine the progress of a transaction by monitoring the various task-completion events (see Sect. 3.8). OSS application will normally process the information accompanying event notifications, for example, to correlate alarms or accumulate longer-term statistics, and then make the information available to multiple OSS clients asynchronously.

Fig. 3.6 OSS Event Notification Service

Intent Provide a resilient mechanism to permit OSS applications to asynchronously notify OSS clients of event occurrences.

Motivation OSS applications need to notify multiple OSS clients about event occurrences at unpredictable times, and OSS clients need to be able to select the types of events about which they are prepared to receive information and the rate at which they are prepared to receive it.

42

3 OSS Architectural Patterns

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

Fig. 3.7 Use of OSS Event Notification Pattern

Example OSS Session Profile 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

3.3 OSS Event Notification Pattern

43

ObjectMessage—a serializable Java object. In the following example code, we will

illustrate how an event, the creation of an inventory record managed-entity, notified by the Simple Inventory application, might be handled by a Java client. We first define the BaseEvent and RecordCreateEvent interfaces that will give access to the payload of the message: /** * Base interface to access the payload of all Simple * Inventory event notification messages */ public interface BaseEvent extends java.io.Serializable { /* * Accessor for the time the event was published as a String */ public String getEventTimeAsString(); /* * Accessor for the time the event was published */ public Calendar getEventTime() 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() throws ApplicationException; 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 method verifies that the message is a notification of the creation of an inventory record managed-entity, extracts the contents, and prints the content details. /** * Implementation of the onMessage method to handle * receiving a record-creation event notification * */ public class OSSListenerImplementation implements javax.jms.MessageListener { public void onMessage(Message message) { System.out.println("\nMessage Received--->");

44

3 OSS Architectural Patterns

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

3.3 OSS Event Notification Pattern

45

* Create a JNDI InitialContext object if none exists * */ try { jndiContext = new InitialContext(); } catch (NamingException e) { System.out.println("Could not create JNDI API context: " + e.toString()); System.exit(1); } /* * look-up connection factory and destination. */ try { connectionFactory = (ConnectionFactory) jndiContext.lookup( topicFactory); dest = (Destination) jndiContext.lookup(destName); } catch (Exception e) { System.out.println("JNDI API lookup failed: " + e.toString()); System.exit(1); } /* * Create the connection. */ connection = connectionFactory.createConnection(); session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE); consumer = session.createConsumer(dest); MessageListener listener = new OSSListenerImplementation(); /* * Register the listener and start delivery */ consumer.setMessageListener(listener); connection.start();

The report of the creation of an equipment record managed-entity will look like this: Message Received---> Message type: RecordCreateEvent notification Event Time= 2009 3 3 1h37 50s Notification content: Equipment Record Value: RecordId = 42 RecordType = EquipmentRecordType LastUpdateVersionNumber = 1234 RecordCreationDate = 2009 3 3 1h37 49s EquipmentType = LineCard NumberOnHand = 10 Location = Montreal

OSS Message Profile Example In this OSS Message Profile example, we will again use the Java Message Service (JMS) to implement the OSS Event Notification pattern. The JMS message will be of type TextMessage—a text message that contains an event-notification document.

46

3 OSS Architectural Patterns

The following schema fragment defines the base notification type and the createrecord notification type and element.

The notification payload for the creation of an equipment record managed-entity might look like this: 0) { for (int i = 0; i < recordvos.length; i++) { equipvo = (EquipmentRecordValue) recordvos[i]; System.out.println(equipvo.getEquipmentType() + " " + String.valueOf(equipvo.getNumberOnHand())); } recordvos = iterator.getNextInventoryRecords(5); } iterator.remove();

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

3.4 OSS Iterator Pattern

51

OSS Message Profile Example In order to implement the OSS Iterator pattern in the OSS Message Profile example, we define two additional complex types, IteratorRequest and IteratorResponse, as follows:

The IteratorRequest complex type defined in the above schema fragment includes the element, , to indicate the maximum number of value documents to be returned in the response. The IteratorResponse complex type definition includes two additional elements: , an ordinal indicating the ordering of the response, and , a boolean indicating the last response of the sequence. These complex types are introduced into simple request and response documents by means of the XML Schema element . The schema fragment for the getInventoryRecordsByTemplateRequest and getInventoryRecordsByTemplateResponse types is as follows:

52

3 OSS Architectural Patterns



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

A client might populate the key in the request document as shown below: 42 EquipmentRecordType 1234 2009-04-01T12:15:00-05:00 LineCard 10 Montreal

Summary The OSS Factory pattern centralizes either the definition of, or the implementation of, value objects and documents thus reducing administrative issues associated with application upgrades and vendor-specific extensions. By arranging the definitions in a type hierarchy, polymorphic operations can be supported.

58

3 OSS Architectural Patterns

3.6 OSS Discovery Pattern Reliability of the software that manages telecommunications services is of great importance because of the critical nature of telecommunications. Type safety is an important aspect of the design of reliable software and, for that reason, OSS client implementations are normally strongly typed. However, strong typing of OSS clients makes it difficult for them to take advantage of newer, or vendor-enhanced, OSS applications without some sort of modification. We need to provide a mechanism to allow operators to take advantage of updated or vendor-enhanced OSS applications without the need to modify and re-build the OSS client. Intent Provide OSS clients with a mechanism to dynamically discover the functionality of OSS applications. Motivation As we have noted, type safety is an important part of software design. One of the ways of achieving type safety is to make interfaces strongly typed, and to implement them using statically-typed programming languages such as Java or staticallytyped schemata, such as at XML Schema[3]. Static typing allows type errors to be detected at compile time or at XML document generation time. However, staticallytyped interfaces and schemata imply a tight coupling between OSS client and OSS application. To take advantage of upgraded or vendor-enhanced OSS applications, statically-typed OSS clients have to be modified, and that can lead to a proliferation of versions of OSS clients. We need to provide a mechanism for OSS clients to discover and use the functionality of an OSS application at runtime. Solution Require OSS applications and managed-entity values to expose metadata about the functionality they offer. Using this metadata, an OSS client can dynamically build a request (see Fig. 3.11) or process the results from a request (see example section below). For example, a vendor-enhanced trouble-ticket managed-entity value might expose metadata about additional fields in a trouble ticket; a generic operatorsupport application can present those additional fields to the operator. Or an OSS application might expose metadata to enable an operator to discover, and subscribe to, event types supported by an OSS application. Metadata about the following is typically useful: • • • • • •

operations supported; attribute names supported; managed-entity types supported; named-procedure and query types supported; attributes of managed-entity types supported; and event types supported.

3.6 OSS Discovery Pattern

59

Discovering functionality at runtime can compromise type safety, and a software designer needs to carefully strike a balance between, on the one hand, type-safety and performance, and on the other, flexibility.

Fig. 3.11 Use of the OSS Discovery Pattern

Example In the following examples, we will illustrate the use of the OSS Discovery pattern to develop generic browsers to allow clients to browse the names of the managed entities exposed by the session and message fac¸ades and the names and types of their attributes. OSS Session Profile Example Since the implementation of managed-entities is hidden, the client must discover the information about managed entities from the managed-entity value interface in the session profile. In the following code, the client first gets a reference to a Simple Inventory session bean, and then discovers, from it, the names of the managed-entity types—in this case, the names of the inventory record managed-entity types.

60

3 OSS Architectural Patterns

For each inventory record managed-entity type, the client requests the creation of an inventory record managed-entity value-object and, from each, discovers the names of the respective managed-entity attributes. By introspecting the accessors of the field names of each managed-entity value, the client discovers the respective field types and hence can infer the types of the corresponding managed-entity attributes. /** * Example of OSS Discovery pattern use: a generic managed entity browser */ SimpleInventorySession session; ManagedEntityValue ir1; ServiceLocator serviceLocator = new ServiceLocator(); String[] entityTypes; /* * Get the session bean */ session = serviceLocator.getInventorySession(); /* * 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); }

3.6 OSS Discovery Pattern

61

The output of browsing the Simple Inventory fac¸ade will look like this: Managed-entity value-type: ManagedEntityValue Attribute name: RecordKey (simpleinventory.RecordKey) Attribute name: LastUpdateVersionNumber (long) ---------------------------------------------Managed-entity value-type: simpleinventory.InventoryRecordValue Attribute name: 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) ---------------------------------------------...

OSS Message Profile Example As for the session profile, we will illustrate the OSS Discovery pattern by developing a generic managed-entity browser to browse the names of the managed entities exposed by the message fac¸ade and the names and types of their attributes. Since the client does not know the implementation of the managed-entities, it must discover the information about the managed entities from the fac¸ade XML schema. In the code fragment below, the client first gets a reference to the schema and then parses the schema to build a list of global element specifications that corresponds to the managed-entity types. The client then iterates over the global element specifications to discover each of the names and types (these correspond to the names and types of the managed entities exposed by the fac¸ade), and iterates over each of the child element types to discover the names and types (these correspond to the names and types of the attributes of the managed entities). /** * Example of OSS Discovery pattern use: a generic schema browser */ SchemaGlobalElement element; //schemaFile = ... set location of schema file File schema = new File(schemaFile); SchemaTypeSystem schemaTypeSystem = null; /* * Parse the schema into a list of global element specifications */ schemaTypeSystem = XmlBeans.compileXsd(new XmlObject[]{ org.apache.xmlbeans.XmlObject.Factory.parse(schema)}, XmlBeans. getBuiltinTypeSystem(), null); SchemaGlobalElement[] elements = schemaTypeSystem.globalElements(); List list = Arrays.asList(elements);

62

3 OSS Architectural Patterns

/* * Iterate over the list get the global element names and types */ for (Iterator iterator = list.iterator(); iterator.hasNext();) { element = (SchemaGlobalElement) iterator.next(); System.out.println("Element Name: " + element.getName().getLocalPart()); System.out.println("Element Type: " + element.getType()); /* * Print out the child elements--the attribute names and types */ printElementChildren(element); } } /** * Print out the names and types of child elements of input element * */ public void printElementChildren(SchemaGlobalElement element) { SchemaType xyz = element.getType(); SchemaParticle toto = xyz.getContentModel(); SchemaParticle[] atts = null; if (toto != null) { if (toto.getParticleType() == SchemaParticle.SEQUENCE) { atts = toto.getParticleChildren(); } if (atts != null) { for (int kk = 0; kk < atts.length; kk++) { System.out.println("Attribute Name " + atts[kk].getName()); System.out.println("Attribute Type " + atts[kk].getType().getName()); if (atts[kk].getParticleType() == SchemaParticle.ELEMENT) { SchemaLocalElement zzz = (SchemaLocalElement) atts[kk]; } } } } System.out.println("-----------------------------------------------------"); }

The output of browsing the Simple Inventory fac¸ade schema will look like this: Element Name: inventoryRecordKey Element Type: T=RecordKeyType@http://xml.netbeans.org/schema/Entities Attribute Name {http://xml.netbeans.org/schema/Entities}recordId Attribute Type {http://www.w3.org/2001/XMLSchema}string Attribute Name {http://xml.netbeans.org/schema/Entities}recordType Attribute Type {http://www.w3.org/2001/XMLSchema}string ----------------------------------------------------Element Name: managedEntityValue Element Type: T=ManagedEntityValueType@http://xml.netbeans.org/schema/Entities Attribute Name {http://xml.netbeans.org/schema/Entities}recordKey Attribute Type {http://xml.netbeans.org/schema/Entities}RecordKeyType Attribute Name {http://xml.netbeans.org/schema/Entities}lastUpdateNumber Attribute Type {http://www.w3.org/2001/XMLSchema}long ----------------------------------------------------Element Name: inventoryRecordValue Element Type: T=InventoryRecordValueType@http://xml.netbeans.org/schema/Entities Attribute Name {http://xml.netbeans.org/schema/Entities}recordKey Attribute Type {http://xml.netbeans.org/schema/Entities}RecordKeyType

3.6 OSS Discovery Pattern

63

Attribute Name {http://xml.netbeans.org/schema/Entities}lastUpdateNumber Attribute Type {http://www.w3.org/2001/XMLSchema}long Attribute Name {http://xml.netbeans.org/schema/Entities}creationDate Attribute Type {http://www.w3.org/2001/XMLSchema}dateTime ----------------------------------------------------Element Name: equipmentRecordValue Element Type: T=EquipmentRecordValueType@http://xml.netbeans.org/schema/Entities Attribute Name {http://xml.netbeans.org/schema/Entities}recordKey Attribute Type {http://xml.netbeans.org/schema/Entities}RecordKeyType Attribute Name {http://xml.netbeans.org/schema/Entities}lastUpdateNumber Attribute Type {http://www.w3.org/2001/XMLSchema}long Attribute Name {http://xml.netbeans.org/schema/Entities}creationDate Attribute Type {http://www.w3.org/2001/XMLSchema}dateTime Attribute Name {http://xml.netbeans.org/schema/Entities}equipmentType Attribute Type {http://www.w3.org/2001/XMLSchema}string Attribute Name {http://xml.netbeans.org/schema/Entities}numberOnHand Attribute Type {http://www.w3.org/2001/XMLSchema}int Attribute Name {http://xml.netbeans.org/schema/Entities}location Attribute Type {http://www.w3.org/2001/XMLSchema}string ----------------------------------------------------...

Summary The OSS Discovery pattern allows developers to strike a balance between type safety and future proofing in the design of interfaces to OSS applications.

64

3 OSS Architectural Patterns

3.7 OSS Named-Procedure Pattern During the life cycle of an OSS application, new operations and queries may need to be added to extend functionality and accommodate vendor-specific extensions. In addition, not all of the day-to-day tasks of network managers can be supported by OSS clients that implement patterns such as the Managed-Entity Update pattern (see Sect. 4.3) or the Managed-Entity Template Filter pattern (see Sect. 4.5). A number of routine, but important, tasks may be quite complex and may be the subject of complex business or consistency rules that evolve over time. Other tasks might be complex, but routine, queries that are not amenable to associative look-up techniques.

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

Motivation It is not usual to be able to predict all of the operations that are needed during the design of an OSS application; it is often necessary to add operations as applications mature and new requirements are identified. If new operations were to be added to the fac¸ade, it would lead to a proliferation of operations and require the repeated re-compilation and redeployment of clients to take advantage of the new features. In addition, relying on OSS clients to correctly validate operator input to complex procedures invoked on OSS applications adds complexity to the OSS clients and is risky from an operational perspective. Allowing operators to invoke complex queries based on just associative lookup techniques can have consequences in terms of performance and availability of OSS applications.

Solution Use strongly-typed value types to carry the name and the parameters of named procedures to OSS applications and to return results. The general approach is for OSS applications to define value types for the named procedures that OSS clients can either obtain, or locally instantiate, and populate with the required parameters. When an OSS application receives such a value instance, it can validate the parameters and apply any business or consistency rules before carrying out the procedure. The application returns any results as a value type. Fig. 3.12 illustrates the approach. In addition to centralizing validation, the pattern centralizes the maintenance of the business and consistency rules. It can also reduce network traffic by replacing a

3.7 OSS Named-Procedure Pattern

65

Fig. 3.12 Use of the OSS Named-procedure Pattern

number of simple operations with fewer, higher-value, operations. The pattern also helps reduce complexity in OSS clients. In collaboration with the OSS Discovery pattern (see Sect. 3.6) and the OSS Factory pattern (see Sect. 3.5), the pattern can help OSS clients accommodate updates or vendor-specific extensions to OSS applications without modification. The pattern is based on the Command pattern[9]. Example Using the Simple Inventory application, suppose we want to routinely obtain a list of all the equipment records, filtered by location, that have fallen below their reorder level. Given only the Managed-Entity Template Filter pattern, we would have to bring back to the client managed-entity values representing all of the equipment records for the desired location and locally select those where the number-on-hand had dropped below the re-order level—not a pretty solution. A better solution is to do the filtering on the OSS and return only the relevant managed-entity values. We will define a named procedure to do just that. OSS Session Profile Example In the OSS Session Profile, and using Java, we first declare the base interfaces for the Named-procedure request and response value objects: /** * Base interface for the named-procedure-request value-objects */ public interface NamedProcedureRequest extends java.io.Serializable { }

66

3 OSS Architectural Patterns

/** * 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-reorderitems request interface, and extend Named-procedure response and the Inventoryrecord value Iterator interfaces to declare the Query-reorder-items response interface: /** * Query re-order-items request interface */ public interface QueryReorderItemsRequest extends NamedProcedureRequest { public static final String LOCATION = "location"; /** * mutator for the single parameter "location" */ void setLocation(String location); }

/** * Query re-order-items response interface */ public interface QueryReorderItemsResponse extends NamedProcedureResponse, InventoryRecordValueIterator { }

The following snippet of code requests a Query-reorder-items request value-object from the session bean, populates with the value “Toronto”, and invokes the query on the Simple Inventory application. The application responds with an iterator that can be used to fetch the value objects corresponding to the extended equipment-records where the items on-hand have fallen below the re-order level. /* * Named-procedure example * Request list of equipment-levels by location that * have fallen below the re-order level */ SimpleInventorySession session; QueryReorderItemsRequest query; InventoryRecordValueIterator iterator; InventoryRecordValue recordvos[]; InventoryRecordValue irvo; /* * Get Simple Inventory session bean */ ServiceLocator serviceLocator = new ServiceLocator();

3.7 OSS Named-Procedure Pattern

67

session = serviceLocator.getInventorySession(); //get a QueryReorderItemsValue object query = (QueryReorderItemsRequest) session.makeNamedProcedureRequest( "simpleinventory.QueryReorderItemsRequest"); //set the location field in the template query.setLocation("Toronto"); iterator = (InventoryRecordValueIterator) session.execute(query); //process 10 equipment record value-objects at a time recordvos = iterator.getNextInventoryRecords(10); while (recordvos.length > 0) { for (int i = 0; i < recordvos.length; i++) { irvo = recordvos[i]; System.out.println(irvo.toString()); } recordvos = iterator.getNextInventoryRecords(10); } iterator.remove();

The output might look like this: Equipment Record Value: Equipment type = LineCard Number on hand = 9 Location = Toronto Reorder level = 10 Supplier Name = Nortel Equipment Record Value: Equipment type = PowerSupply Number on hand = 25 Location = Toronto Reorder level = 27 Supplier Name = Acme ...

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

68

3 OSS Architectural Patterns



We next extend the NamedProcedure request and response type specifications to include the iterator request and response element definitions to allow the client to control the flow of information returned from the OSS application.

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

3.7 OSS Named-Procedure Pattern

69



Using the QueryReorderItems request schema, we next make an instance of the query and populate the element with the value 2 (that is requesting at most two extended-equipment record value-documents be returned), and element with the value “Toronto”. 1 false

70

3 OSS Architectural Patterns

42 EquipmentRecordType 1234 2009-04-01T12:15:00-05:00 LineCard 9 Toronto 10 Nortel 4242 EquipmentRecordType 5678 2009-04-01T12:19:00-05:00 LineCard 25 Toronto 27 Acme

Summary The Named-procedure pattern provides an extensible, but strongly-typed, method of defining procedures or queries during the lifetime of an OSS application. It is based on the Command pattern[9] and, like the Command pattern, the value type carries the procedure name and the request parameters.

3.8 OSS Command–Status Pattern

71

3.8 OSS Command–Status Pattern Some OSS management tasks involve multiple operations, and those operations involving manual intervention may last for long periods of time, often measured in days. For example, a Customer Relationship Management (CRM) application might initiate the processing of a customer order. Customer orders for service can be longlived involving a number of operations, some of which might be assigned to OSS applications such as work-order and configuration applications that involve manual intervention. Rather that maintain the session with the client for the duration of the transaction, the CRM application acknowledges the request and informs the client of the progress of the request through a series of asynchronous notifications.

Fig. 3.13 Example of the Use of the OSS Command–Status Pattern

Intent Minimize the amount of session information that an OSS client needs to retain in order to complete long-lived requests.

72

3 OSS Architectural Patterns

Motivation Some requests may take a long time to complete and requiring OSS clients to maintain session information about such requests can be impractical. However, the client needs to know when a request has been completed and ideally the progress of the request in the interim.

Solution The OSS application sends periodic event notifications to inform the OSS client of the progress of the request and when it has been completed.

Example In the example shown in Fig. 3.13, we show how the Command–Status pattern might be used for a long procedure, that of restoring the Simple Inventory database from backup. The OSS client requests a named-procedure value-type to initiate a restore of the Simple Inventory from backup, and sets the backup information field to request a full restore. The client then invokes the restore procedure, receives an acknowledgment, and waits for notifications. As the restore procedure executes, the client receives progress information in the form of event notifications. OSS Session Profile Example The following code illustrates how the Command–Status pattern might be used in the session profile. The client requests and populates a restore-from-backup-request value-object from the session bean and populates it to request a full restore. It invokes the restore-from-backup-request using the execute() operation on the session bean, and exits waiting for event notifications using the onMessage() implementation shown in Sect. 3.3. SimpleInventorySession session; RestoreFromBackupRequest request; RestoreFromBackupResponse response; /* * Get Simple Inventory session bean */ 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 notification Event Time= 2009 3 3 1h23 14s Notification content: Restore status=STARTED Completion=0% Message Received---> Message type: RestoreFromBackUpStateEvent notification Event Time= 2009 3 3 2h26 19s Notification content: Restore status=INPROGRES Completion=25% Message Received---> Message type: RestoreFromBackUpStateEvent notification Event Time= 2009 3 3 4h45 24s Notification content: Restore status=INPROGRES Completion=50% Message Received---> Message type: RestoreFromBackUpStateEvent notification Event Time= 2009 3 3 6h21 29s Notification content: Restore status=INPROGRES Completion=75% Message Received---> Message type: RestoreFromBackUpStateEvent notification Event Time= 2009 3 3 7h23 34s Notification content: Restore status=COMPLETED Completion=100%

Summary The OSS Command–Status pattern allows an OSS client to maintain minimal session 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 notifications about progress and completion to the OSS client.

3.9 Summary In this chapter, we have looked at a number of architectural patterns that we have found useful in developing interfaces to OSS applications. Some patterns focus on consistency, some on efficiency, and some balance the need for flexibility with the need for safety. In the next chapter we will build on these patterns and look at a number of useful programming patterns.

74

3 OSS Architectural 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. Fac¸ade 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 4

OSS Programming Patterns

To understand is to perceive patterns. Isaiah Berlin

In the previous chapter we introduced a number of architectural patterns; in this chapter we will use them as a foundation to introduce a number of programming patterns. Two important patterns are the Managed-Entity Update pattern and the Managed-Entity Life cycle pattern both of which support a CRUD (Create, Read, Update, Delete) style of modification.

4.1 Managed-Entity Key Pattern In managing telecommunications services, it is important to be able to unambiguously reference a managed resource; for example, to be able to reference a particular trouble ticket to update its status or to be able to reference a particular piece of communications equipment to configure it.

Intent Provide a mechanism to unambiguously refer to managed entities.

Motivation In the OSS Managed-Entity Model (see Sect. 2.6), managed resources are modelled as managed entities so, to refer to a managed resource, an OSS client must actually refer to the managed entity that models the resource. (As we saw in Sect. 2.6, it is the responsibility of the OSS application to maintain the relationship between the managed resource and the managed entity.) Therefore to get an unambiguous reference to a managed resource, we actually need to get an unambiguous reference to a managed entity.

75

76

4 OSS Programming Patterns

Solution All managed entities expose a key whose value is unique with respect to the other managed entities within the application context. The application context is that naming 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 algorithm used to determine equality of keys; the only requirement is that the value of the key uniquely identify the managed entity within the application context. When creating a managed entity, an OSS client can choose to assign the value of the key or request that the OSS application assign the value of the key. In either case it is the responsibility of the application to ensure the value of the key is unique. In order for a client to create a key, the OSS application must make the structure of the key available either by means of a factory method or by means of a schema.

Fig. 4.1 The Simple Inventory Key Model

Example To illustrate the creation of keys, we will show how a client might obtain, populate, and use a managed-entity key. The key structure of the Simple Inventory is, as you might expect, fairly simple. It is two level structure: a naming context (Record Type) and an identifier (ID) within that context, see Fig. 4.1. OSS Session Profile Example In the following Java example using the OSS Session Profile, the OSS client first gets a reference to a Simple Inventory session bean. It next requests the session bean to make an equipment record value-object, and then uses it to create a record

4.1 Managed-Entity Key Pattern

77

key. The OSS client then populates the key, and requests an equipment record valueobject corresponding to the key. /* * Managed-entity Key Pattern Example--make a record key */ EquipmentRecordValue recordvo; RecordKey key; SimpleInventorySession session; /* * Get Simple Inventory session bean */ 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());

Running the above code might result in the following output: Equipment Record Value: Record Id = 42 Record Type = EquipmentRecordType LastUpdateVersionNumber = 1234 RecordCreationDate = 2009 4 1 12h15 EquipmentType = LineCard NumberOnHand = 10 Location = Montreal

OSS Message Profile Example To use a managed-entity key in the message profile, an OSS client would either have the schema for the key available locally or would obtain it from an external repository (see Sect. 3.5).

78

4 OSS Programming Patterns

The following is the XML Schema for the and elements for the Simple Inventory:

A client might populate the key in the request document as shown below: 42 EquipmentRecordType 1234 2009-04-01T12:15:00-05:00 LineCard 10 Montreal

Summary The Managed-Entity Key pattern is a flexible way to unambiguously refer to managed entities within an application context and hence unambiguously refer to managed resources. The key structure and key matching algorithm are the responsibility of the OSS application; the key structure is made available to OSS clients by use of the OSS Factory Pattern (see Sect. 3.5).

80

4 OSS Programming Patterns

4.2 Managed-Entity Life Cycle Pattern As part of managing telecommunications services, we need to be able to model the life cycle of managed resources. Logical resources, such as inventory records, are created and deleted, and physical resources, such as line cards are activated or de-activated.

Intent Provide a mechanism to model the life cycle of managed resources.

Motivation Managed entities are a consistent way to model the management aspects of managed resources whether those resources be logical resources or physical resources. We need to be able to model the creation of logical resources, such as the creation of a trouble ticket, and the activation of physical resources, such as the activation of a line card. And, of course, we need to model the reverse: the deletion of a trouble ticket and the deactivation of a line card. In the Managed-Entity model, we could do this by respectively creating and deleting the managed entities that represent the managed resources, but the OSS Reference Architecture (see Sect. 2.3) does not prescribe the implementation of managed entities, and that leaves us in a bit of a quandary.

Solution Use the Managed-Entity Value pattern to create managed entities. A single managed entity is created by populating a managed-entity value with the desired values for the managed-entity attributes and sending the managed-entity value to the fac¸ade as an argument to a create request (see Fig. 4.2). Attributes corresponding to fields not populated in the managed-entity value are set to default values by the fac¸ade. The successful creation of the managed entity indicates the successful creation or activation of the managed resource. A single managed entity is deleted by sending a suitably populated key as an argument to a delete request. The successful deletion of the managed entity indicates the successful deletion or de-activation of the managed resource. So far, we have only talked about the creation and deletion of single managed entities, but bulk creation and deletion operations are useful. For example, the creation of multiple managed entities with the same attribute values, the creation of multiple managed entities with different attribute values, and the deletion of multiple managed entities with the same attribute values (see Sect. 4.6).

4.2 Managed-Entity Life Cycle Pattern

81

Fig. 4.2 An Example Managed-Entity Life Cycle

Example In the following examples, we will show how clients might create and delete an equipment record managed-entity in the Simple Inventory. OSS Session Profile Example In the session profile example below, the OSS client uses the OSS Factory pattern to make an empty managed-entity value-object, populates it with the desired values, and then requests the session bean to create the managed entity that, in turn, creates the corresponding record in the inventory. The client then tests the key, and finally deletes the managed-entity. /* * Equipment Record Life Cycle Example */ EquipmentRecordValue recordvo, recordvo2; RecordKey key; String[] meTypes; SimpleInventorySession session;

82

4 OSS Programming Patterns

/* * Get Simple Inventory session bean */ ServiceLocator serviceLocator = new ServiceLocator(); session = serviceLocator.getInventorySession(); /* * 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 */ recordvo = (EquipmentRecordValue) session.makeManagedEntityValue( 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) */ key = recordvo.makeRecordKey(); /* * Populate the key */ key.setRecordId("42"); key.setRecordType("EquipmentRecordType"); /* * 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);

4.2 Managed-Entity Life Cycle Pattern

83

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 valueobject.1 4. Set the required attribute values in the equipment record value-object. 5. Use the equipment record value-object as a factory to create a record key and populate the key. 6. Request the session bean to create the equipment record managed-entity with the value-object as a parameter (the Simple Inventory application will create the corresponding equipment record). 7. Request a new equipment record value-object corresponding to the key that was returned and print the record values. 8. Delete the equipment record managed-entity using the key (the Simple Inventory application will delete the corresponding equipment record). Running the above code will result in the following output: ME ME ME ME ME

TYPE= TYPE= TYPE= TYPE= TYPE=

ManagedEntityValue simpleinventory.InventoryRecordValue simpleinventory.EquipmentRecordValue simpleinventory.ExtendedEquipmentRecordValue simpleinventory.SupplierRecordValue

Equipment Record Value: Record Id = 42 Record Type = EquipmentRecordType LastUpdateVersionNumber = 1234 RecordCreationDate = 2009 4 1 12h15 EquipmentType = LineCard NumberOnHand = 10 Location = Montreal

OSS Message Profile Example In the following JMS example using the message profile, the OSS client obtains a copy of the schema for the request element, creates an XML document conforming to the schema, populates it with the desired values, and sends it to the fac¸ade message queue.

1

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

84

4 OSS Programming Patterns

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

In the above XML schema fragment, the CreateInventoryRecordByValueRequestType complex type specifies an element named, , of type of InventoryRecordValueType implying the creation of an inventory record managed-entity. However, the client wishes to create an equipment record managed-entity that is an extension of inventory record managed-entity. Hence, in the following document, the client uses the xsi:type attribute in the opening tag to indicate that the additional elements of the EquipmentRecordValueType are included. The following is an XML document requesting the creation of the desired equipment record managed-entity: 42 EquipmentRecordType

Summary In creating and deleting managed entities, we take advantage of the Managed-Entity Value pattern (see Sect. 3.1) to reduce the amount of network traffic involved in creating managed entities, and to reduce the number of operations required to create and delete multiple managed entities. By arranging the managed-entity value definitions in a type hierarchy, we can exploit the polymorphic features of Java and XML Schema.

86

4 OSS Programming Patterns

4.3 Managed-Entity Update Pattern Many management tasks, such as updating inventory records or configuring of simple equipment, can be supported by a simple read-update model.

Intent Provide an effective mechanism to support a read-update model.

Fig. 4.3 Use of the Managed-Entity Update Pattern

Motivation Many OSS applications are amenable to a read-update model of engagement, but reading or updating a number of attributes with a series of requests can be impractical because of latency in the network and the communications overhead.

Solution Use a managed-entity value to read or update multiple attribute values of a managed entity in a single request. In Fig. 4.3 we show a sequence diagram illustrating how

4.3 Managed-Entity Update Pattern

87

an OSS client might update a managed entity. The client first gets a managed-entity value corresponding to the managed entity in question. The client updates the fields of the managed-entity value locally, and then returns the managed-entity value to the fac¸ade with a request to write the new values back to the managed entity and, by extension, to the managed resource. Only attributes that are to be updated need be included in the managed-entity value.

Example OSS Session Profile Client code, written in Java and using the session profile, to update the attribute values of a managed entity representing a record in the Simple Inventory might look like this: /* * Update Equipment Record Managed Entity Example */ int number, newNumber; SimpleInventorySession session; /* * Get the session bean */ session = serviceLocator.getInventorySession(); /* * 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 */ recordvo = (EquipmentRecordValue) session.getInventoryRecordByKey(key, null); System.out.println(recordvo.toString()); //update value-object copy number = recordvo.getNumberOnHand(); newNumber = number - 1; recordvo.setNumberOnHand(newNumber); //and write it back to update the equipment record managed-entity session.setInventoryRecordByValue(recordvo, false); //Get the recordvo again and print it recordvo = (EquipmentRecordValue) session.getInventoryRecordByKey(key, null); System.out.println(recordvo.toString());

88

4 OSS Programming Patterns

The OSS client creates an instance of a Simple Inventory session bean and requests, from the session bean, an equipment record value-object representing the equipment record managed-entity indicated by the supplied key. Having received the equipment record value-object, the client then locally updates the values using the equipment record value-object interface. The client finally requests that the updated value-object be written back to update the equipment record managed-entity and hence to update the equipment record that the managed entity represents. The output might look like this: Equipment Record Value: Record Id = 42 Record Type = EquipmentRecordType LastUpdateVersionNumber = 1234 RecordCreationDate = 2009 4 1 12h15 EquipmentType = LineCard NumberOnHand = 10 Location = Montreal Equipment Record Value: Record Id = 42 Record Type = EquipmentRecordType LastUpdateVersionNumber = 1234 RecordCreationDate = 2009 4 1 12h15 EquipmentType = LineCard NumberOnHand = 9 Location = Montreal

OSS Message Profile In the following JMS example, using the message profile, the client populates a getInventoryRecordByKey request document with the appropriate key using the schema fragment shown in Sect. 4 .1 , p. 78 and enqueues it onto the queue for the Simple Inventory application: 42 EquipmentRecordType 1234 2009-04-01T12:15:00-05:00 LineCard 10 Montreal

Note that the schema fragment defining the getInventoryRecordByKeyResponse document in Sect. 4 .1 , p. 78, defines an element named, , of type InventoryRecordValueType. However, the type of the element returned is actually EquipmentRecordValueType, an extension of InventoryRecordValueType; this is noted by the inclusion of the xsi:type attribute of the element. The client then updates the number-on-hand locally, and requests the equipment record managed-entity be updated by enqueueing the following document onto the Simple Inventory application queue: , with two child elements with content of “numberOnHand” and “location” respectively indicating that only the numberOnHand and Location managed-entity attributes are to be returned: 42 EquipmentRecordType 1234 2009-04-01T12:15:00-05:00 10 Montreal

In the subsequent update of the managed entity, we “un-populate” the attribute by simply not sending it: 0) { for (int i = 0; i < recordvos.length; i++) { equipvo = (EquipmentRecordValue) recordvos[i]; System.out.println(equipvo.getEquipmentType() + " " +

4.5 Managed-Entity Template Filter Pattern

97

String.valueOf(equipvo.getNumberOnHand())); } recordvos = iterator.getNextInventoryRecords(5); } iterator.remove();

The client code above executes a getInventoryRecordsByTemplate() request but, because the parameter (i.e. the template) is of type EquipmentRecordValue, the operation will only match equipment record managed-entities and extendedequipment record managed-entities. OSS Message Profile Example In the message profile example, an extra element named of type InventoryRecordValueType is added the request document to carry the values of the attributes to be matched.

To illustrate the use of the Managed-Entity Template pattern in the message profile, we will use the same example as in the session profile example—making a list of all the equipment items on hand in Montreal. The following XML document re-

98

4 OSS Programming Patterns

quests equipment record value-documents, two at a time, for all equipment records where the location is “Montreal”. The element type in the document is derived from the type defined by the schema fragment (i.e. InventoryRecordValueType) by use of the xsi:type attribute indicating that equipment record managed-entities and extended-equipment record managed entities are to be matched. 1 false 42 EquipmentRecordType 1234 2009-04-01T12:15:00-05:00 LineCard 10 Montreal

4.5 Managed-Entity Template Filter Pattern

99

4242 EquipmentRecordType 5678 2009-04-01T12:19:00-05:00 PowerSupply 25 Montreal 27 Acme

Summary The Managed-Entity Template pattern is a simple, but effective, query-by-example mechanism for the associative addressing of managed entities. In our experience, it meets the majority of query requirements in telecommunications management. However, more sophisticated queries can be implemented using the OSS Namedprocedure pattern (see Sect. 3.7).

100

4 OSS Programming Patterns

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

Intent To provide a mechanism to update multiple managed entities in one request.

Motivation For reasons of bandwidth conservation, network latency, consistency of result, or convenience, it is useful for an OSS client to be able to apply a single update to multiple managed entities into one request.

Solution Provide bulk managed-entity operations such as: • • • •

Update a number of managed entities with the same attribute values. Update a number of managed entities with different attribute values. Create a number of managed entities with the same attribute values. Create a number of managed entities with different attribute values.

In all cases, atomic execution is assumed—that is either the operation is carried on all the requested managed entities or it is carried out on none.

Example In the following example, using the Simple Inventory, we want to update two inventory records to reflect that a number of line cards have been transferred from

4.6 Managed-Entity Bulk Update Pattern

101

Montreal to Toronto. Clearly we must make sure that both updates occur atomically because if either fails, we will have inconsistencies in the inventory. OSS Session Profile Example The Java client code might look like this (we have ignored error checking for the sake of clarity): /* * Atomic Update of equipment record managed-entity Example */ int number, newNumber; EquipmentRecordValue r1vo, r2vo;

// session = ... // key1 = ... // key2 = ...

set up the session set key to Montreal Record set key to Toronto record

/* * Get an equipment record value objects for Montreal and Toronto */ r1vo = (EquipmentRecordValue) session.getInventoryRecordByKey(key1, null); System.out.println(r1vo.toString()); r2vo = (EquipmentRecordValue) session.getInventoryRecordByKey(key2, null); System.out.println(r2vo.toString()); // decrement number on hand of local copy of Montreal record number = r1vo.getNumberOnHand(); newNumber = number - 5; r1vo.setNumberOnHand(newNumber); // increment number on hand of local copy of Toronto record number = r2vo.getNumberOnHand(); newNumber = number + 5; r2vo.setNumberOnHand(newNumber); //prepare the atomic update EquipmentRecordValue[] ervos = new EquipmentRecordValue[2]; ervos[0] = r1vo; ervos[1] = r2vo; //and atomically update the equipment record managed-entities try { session.setInventoryRecordsByValues(ervos); } catch (ApplicationException e) { //process exception... }

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

102

4 OSS Programming Patterns

OSS Message Profile Example For the message profile, we will use the same example—the atomic update of two equipment records. First we will define the schema fragments for the setInventoryRecordsByValues request and response documents:

We next use the above schema fragment to define a setInventoryRecordsByValues instance document with the updated values for the inventory record managedentities, and enqueue the document onto the queue for the Simple Inventory application:

114

A Type Definitions for the Simple Inventory



The schema for the message and notification complex-types and element-types is as follows:

A.2 OSS Message Profile Declarations

115





A.2 OSS Message Profile Declarations



117

118

A Type Definitions for the Simple Inventory



A.2 OSS Message Profile Declarations



119

Appendix B

Implementing an OSS Client Using JAXB

To illustrate the use of patterns in the OSS Message Profile, we have shown examples of the XML messages that a client might use to access OSS applications via a message-driven bean (see Fig. 3.5, p. 39). For the sake of clarity, we have not shown any supporting code for generating the messages, enqueueing the messages, or receiving responses. Within the JEE platform, there are a number tools and APIs that help in the development of Javabased clients using the message profile. In this chapter we will show how an OSS client might create an equipment record managed-entity within the message profile using Java and the JAXB API. We will also look at the overall implementation architecture for implementing OSS Message Profile using JEE.

B.1 Create Equipment Record Managed-Entity Example The Java Architecture for XML Binding (JAXB[2]) API is a framework for processing XML documents within the Java programming language. The API provides methods for un-marshalling an XML document into a tree of Java objects and, conversely, for marshalling Java objects to an XML message. The Java type information is normally obtained by compiling the relevant XML schema into Java classes by the use of the JAXB binding complier[3]. In the following example, we will show the use of the JAXB API to create an equipment record managed-entity (q.v. Sect. 4.2) in the Simple Inventory. The first step is to compile the relevant XML schemata into Java classes and make the classes available to the OSS client as a package. The schema fragments for the CreateInventoryRecordByValue request and response complex types and EquipmentRecordValueType complex types are as follows.

121

122

B Implementing an OSS Client Using JAXB

First, the CreateInventoryRecordByValue request and response complex types and elements:

And next, the managed-entity value-types:

B.1 Create Equipment Record Managed-Entity Example

123



The following code fragment creates and populates the JAXB equivalents of the CreateInventoryRecordByValueRequestType, the RecordKeyType, and the EquipmentRecordValueType: public void createInventoryByValue() throws JMSException { ObjectFactory objFactory = new ObjectFactory(); // Create a JAXB create-inventory-record-by-value request object CreateInventoryRecordByValueRequestType value = objFactory. createCreateInventoryRecordByValueRequestType(); // Create a JAXB equipment record object and populate it EquipmentRecordValueType rvalue = new EquipmentRecordValueType(); rvalue.setLocation("Montreal"); rvalue.setEquipmentType("LineCard"); rvalue.setNumberOnHand(new Integer(10)); //Create a RecordKey object and populate it RecordKeyType rkXml = new RecordKeyType(); rkXml.setRecordId("42"); rkXml.setRecordType("EquipmentRecordType"); // Set the key field of the equipment record object rvalue.setRecordKey(rkXml); // Set the equipment record field of the request object value.setRecord(rvalue);

The next step is to wrap the request object in its XML element and write it out: JAXBContext jaxbContext = null; JAXBElement 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); }

124

B Implementing an OSS Client Using JAXB

Marshaller marshaller = null; // Create the marshaller that writes the XML file from the Java objects try { marshaller = jaxbContext.createMarshaller(); marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE); } catch (JAXBException ex) { Logger.getLogger(JMSClient.class.getName()).log(Level.SEVERE, null, ex); } // Write the XML file StringWriter writer = new StringWriter(); try { marshaller.marshal(request, writer); System.out.println("XML File to be enqueued = \n" + writer.toString()); } catch (JAXBException ex) { Logger.getLogger(JMSClient.class.getName()).log(Level.SEVERE, null, ex); }

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 queue sendJMSMessageToSimpleInventoryQueue(writer.toString()); //Wait for the reponse on replyToDestination Message msg = consumer.receive(); System.out.println("Received Message=" + msg.toString());

The request message generated and sent by the client to the message-driven bean will look like this: 42 EquipmentRecordType LineCard 10 Montreal

B.2 Message Profile Implementation Software Architecture

125

And the response received by the client will look like this: 42 EquipmentRecordType

B.2 Message Profile Implementation Software Architecture

Fig. B.1 Using JAXB to Create an Equipment Record Managed-Entity

In the message profile example described in Sect. 3.2, the OSS Fac¸ade is implemented by means of a message-drive bean that intercepts XML messages and makes the appropriate method calls on the OSS application. Fig. B.1 shows a more detailed software architecture with the session bean and the marshalling and un-marshalling components. The sequence of operations is as follows: 1. Using the JAXB packages and the JAXB API, the OSS client builds a createinventory-record-managed-entity XML request and enqueues it onto the Simple Inventory queue as described in Sect B.1. 2. Using an implementation of the onMessage() method, the message-driven bean retrieves the XML message from the queue. 3. Using the JAXB API, the message-driven bean un-marshals the XML message into a tree of objects.

126

B Implementing an OSS Client Using JAXB

4. The message-drive bean builds the createInventoryRecordByValue() method and calls the session bean. 5. The session bean executes the method on the OSS application and forwards the response from the OSS application to the message-driven bean. 6. The message-driven bean marshals the response into an XML message. 7. The message-driven bean enqueues the XML message onto the reply queue. 8. The OSS client retrieves the response from the queue.

B.3 Create Equipment Record Managed-Entity Example—Complete Code Here is the complete code for the create equipment record managed-entity example: import import import import import import import import import import import import import import import import import import import import import import import

java.io.StringWriter; java.util.logging.Level; java.util.logging.Logger; javax.jms.Connection; javax.jms.ConnectionFactory; javax.jms.JMSException; javax.jms.Message; javax.jms.MessageConsumer; javax.jms.MessageProducer; javax.jms.Queue; javax.jms.Session; javax.jms.TextMessage; javax.naming.Context; javax.naming.InitialContext; javax.naming.NamingException; javax.xml.bind.JAXBContext; javax.xml.bind.JAXBElement; javax.xml.bind.JAXBException; javax.xml.bind.Marshaller; org.netbeans.xml.schema.appmsg.CreateInventoryRecordByValueRequestType; org.netbeans.xml.schema.appmsg.ObjectFactory; org.netbeans.xml.schema.entities.EquipmentRecordValueType; 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 object CreateInventoryRecordByValueRequestType value = objFactory. createCreateInventoryRecordByValueRequestType(); // Create a JAXB equipment record object and populate it EquipmentRecordValueType rvalue = new EquipmentRecordValueType(); rvalue.setLocation("Montreal"); rvalue.setEquipmentType("LineCard"); rvalue.setNumberOnHand(new Integer(10)); //Create a RecordKey object and populate it RecordKeyType rkXml = new RecordKeyType(); rkXml.setRecordId("42"); rkXml.setRecordType("EquipmentRecordType"); // Set the key field of the equipment record object rvalue.setRecordKey(rkXml); // Set the equipment record field of the request object value.setRecord(rvalue); /* * Wrap the request in its XML element and write it out * */ JAXBContext jaxbContext = null; JAXBElement request = objFactory. createCreateInventoryRecordByValueRequest(value); try { jaxbContext = JAXBContext.newInstance("org.netbeans.xml.schema.appmsg"); } catch (JAXBException ex) { Logger.getLogger(JMSClient.class.getName()).log(Level.SEVERE, null, ex); } Marshaller marshaller = null; // Create the marshaller that writes the XML file from the Java objects try { marshaller = jaxbContext.createMarshaller(); marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE); } catch (JAXBException ex) { Logger.getLogger(JMSClient.class.getName()).log(Level.SEVERE, null, ex); } // Write the XML file StringWriter writer = new StringWriter(); try {

128

B Implementing an OSS Client Using JAXB

marshaller.marshal(request, writer); System.out.println("XML File to be enqueued = \n" + writer.toString()); } catch (JAXBException ex) { Logger.getLogger(JMSClient.class.getName()).log(Level.SEVERE, null, ex); } /* * 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 queue sendJMSMessageToSimpleInventoryQueue(writer.toString()); //Wait for the reponse on replyToDestination Message 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 C

Binding the OSS Patterns to Web Services

In describing the two OSS Implementation Profiles (see Sect. 2.5), we chose to describe the OSS Message Profile by binding the OSS Design Patterns to JMS— that is describing OSS clients that use XML messages carried by JMS. In order to demonstrate the flexibility of our pattern-based approach, we will show how the OSS Design Patterns can be bound to Web Services, see Fig. C.1.

Fig. C.1 Binding the OSS Reference Architecture to Web Services

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

131

132

C Binding the OSS Patterns to Web Services

Defining a Web Service in WSDL WSDL specifications are build up of a number of XML elements, namely: element defines the messages to be exchanged between the OSS client

and the Web Services endpoint. element defines the request, response, and exception messages as-

sociated with an operation. element defines the subset of operations supported by the Web Ser-

vices endpoint. element defines the binding to the carriage protocol (e.g. SOAP). element defines the location of the Web Service—it is an implementation of one or more .

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

C Binding the OSS Patterns to Web Services

133

We next define element with one element, namely createInventoryRecordByValueOperation:

And, finally, we bind the element to SOAP in the document/literal style:

A SOAP message to create an equipment record managed entity might look like this:

134

C Binding the OSS Patterns to Web Services

42 EquipmentRecordType LineCard 10 Montreal

And the response might look like this: 42 EquipmentRecordType

Appendix D

OSS Design Pattern Interaction and Usage The various patterns that we have introduced in this book do not stand alone: many are related and many rely on other patterns. To help the reader understand the relationships 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 relationships between the patterns. The nodes of the graphs represent the patterns and the edges the relationships.

Fig. D.1a OSS Pattern Interactions

135

136

Fig. D.1b OSS Pattern Interactions cont.

D OSS Design Pattern Interaction and Usage

References

137

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

Fig. D.2 OSS Pattern Usage

References 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 in developing the overall software architecture. architectural style An abstract description of software components and the pattern of runtime control and data transfer; examples include client-server, event-based, and communicating processes. configuration The setting of the parameters that control the functioning of the network 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 applications to support customer-service representatives; examples of applications include service activation, billing, and problem reporting and tracking. design pattern A description, in a technology-neutral manner, of the essence of a proven and practical solution to a recurring programming or architectural problem. Digital Subscriber Loop (DSL) A family of technologies that provide digital data transmission over the wires of a local telephone network. Element Management System (EMS) A computer system that manages one or more network elements normally in some sort of sub-network arrangement. end-user application An application, offered to an end user, that leverages the connectivity 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 engagement style between an OSS client and an OSS application. information model A model of information elements, their inter-relationships, and their behaviour.

139

140

Glossary

Java Platform, Enterprise Edition (JEE)TM An environment for developing and deploying enterprise applications. Java Message Service (JMS)TM An API for invoking operations on enterprise messaging systems. Long Term Evolution (LTE) The fourth generation mobile broadband standard. managed entity A model of the management aspects of managed resource; it is by engaging with a managed entity that the corresponding managed resource is managed. managed resource A logical or physical asset that provides a service within the telecommunications network and is manageable; examples of assets include connectivity resources, end-user applications, and support resources. managed system A computer system that hosts or manages managed resources; managed systems can be Element Management Systems (EMSs) that manage one or more connectivity resources, or they can be systems that host resources or enduser services such as inventories, trouble tickets, or email services. managed-entity value A data item that is used as a surrogate for a managed entity and is passed between an OSS client and an OSS application. Management Integration System A server that hosts management-integration applications. management solution A coordination of manual procedures and the functionality of OSS applications that addresses a particular management problem; examples include service fulfillment, problem resolution, and the provisioning of network facilities. management-integration application A software component that coordinates the functionality of OSS applications to deliver a management solution. Network Element (NE) A combination of hardware and software that provides switching, multiplexing, or transmission services. notification service A software component that delivers event reports asynchronously to OSS clients. Operations Support System (OSS) A server that hosts OSS applications. operator system A workstation that hosts the user interface and applications that support the human operator in carrying out his/her management tasks. operator-support application A software component that is responsible for operatortask workflow and validation of operator input. OSS application A software component that manages a particular aspect of a telecommunications system such as a connectivity resource, an end-user service, or a support resource; the OSS application implements the management logic and business rules derived from an analysis of the management requirements.

Glossary

141

OSS client A software component that engages with a remote OSS application to access the latters functionality. OSS Design Pattern A description of an abstract architectural or programming solution to telecommunications management problem that has proven successful in practice. OSS Fac¸ade A view, in terms of remote operations, exposed by an OSS application. OSS integration interface The interface at which OSS application functionality is made available. OSS Message Profile A description of the non-functional aspects of a messageoriented engagement between an OSS client and an OSS application. OSS Reference Architecture A refinement of an architectural style in terms of interaction patterns, granularity of operation, and client-server separation; it is a mapping of the OSS Reference Model into the architectural style. OSS Reference Model A functional decomposition that meets telecommunications management requirements. OSS Session Profile A description of the non-functional aspects of a sessionoriented engagement between an OSS client-component and an OSS application. programming pattern A design pattern that addresses a problem encountered within the overall framework of the software architecture. session-oriented data exchange A style of data exchange between a client and a remote application that includes a preamble to agree the rules for the exchange. sessionless data exchange A style of data exchange between a client and a remote application that does not include any preamble to agree the rules for the exchange; the client normally includes a call-back address for replies. software architecture The specification of the systems architecture in terms of programming and data elements bound to a particular software technology. support resource An asset that supports the revenue-generating services; support resources include trouble tickets, alarm reports, and customer and billing records. systems architecture The architecture of the system that is actually deployed; it may be a direct realization of the software architecture, but may also be complemented by deployment considerations such as clustering and virtualization.

142

Glossary

telecommunications management system A system of distributed computers that supervises and manages a telecommunications network and related services. telecommunications service A service offered by a service provider to customers that leverages a telecommunications network; examples include connectivity services and end-user applications. value type An entity which shares many of the characteristics of interfaces. It is a description of both a set of operations that a client may request and of state that is accessible to a client. Instances of a value type are always local concrete implementations. A value type, in addition to the operations and state defined for itself, may also inherit from other value types, and through inheritance support other interfaces. XML Schema An XML Language for defining the content of XML documents.

About the Authors

Pierre Gauthier is the President and CTO of OSS Wave, a software consulting and training company. For the last decade Pierre has been involved in the design and development of software for telecommunications and Operation Support Systems (OSSs), holding senior positions with Oracle and Nortel. Pierre was the driving force behind the development of the OSS/J Design Guidelines and is Spec Lead for JSR 91, the OSS Trouble Ticket API. Pierre is a JavaOne alumnus,TMF invited speaker, and JCP Star Spec Lead. ´ He holds a master’s degree in Electrical Engineering from the Ecole Polytech´ Canada. nique, Montreal,

Colin Ashford is the owner of the independent consulting company OSSEvolution. Colin is a professional engineer with over twenty-five years experience in the computing and telecommunications industry, primarily concerned with the standardization of distributed systems and telecommunications networks. He has held senior positions in Nortel with responsibilities for international standards and project management. Colin has been an invited speaker at TMF and ECOOP conferences, and is an OSS Through Java Fellow. He holds a master’s degree in Computer Science from Carleton University, Ottawa, Canada.

143

Index

, 83 , 56, 78 , 78 , 98 , 98 , 98 , 52, 98 , 93 , 132 , 51 , 34, 51 , 33 , 69 , 132 , 132, 133 , 132, 133 , 84, 89 , 33 , 51 , 132 , 97

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

OSS client, 8 XML data types, 19

call-back address, 16 CIM, see Common Information Model client-server, 2 client-server style, 3, 14 Command pattern, 65 command-status request pattern, see OSS Command–Status pattern Common Information Model, 13 concurrent updating, 104 configuration, 139 connectivity resource, 3, 8, 139 consistency of result, 100

accessor, 28 adaptation and persistence layer, 7 ADDRESS, 32 alarms, 41 application context, 76, see OSS Application Context application layer, 8, see OSS application layer Application Programming Interface, 17 ApplicationFaultType, 40

bandwidth conservation, 100 BaseEvent, 43 binary encoding, 17 binding of patterns, 17 BPF, see TM Business Process Framework bulk update pattern, see Managed-Entity Bulk Update pattern business problem, 5 Business Process Framework, see TM Business Process Framework business rules, 3

145

146 CONTACTNUMBER, 32 CORBA objects, 8 coupling client/server, 16 Create, Read, Update, Delete model, 20 CreateInventoryRecordByValue, 84, 121, 122 createInventoryRecordByValue(), 38, 126 createInventoryRecordByValueOperation, 133 CreateInventoryRecordByValueRequestType, 84, 123 CREATIONDATE, 31 CRUD, 13, see Create, Read, Updated, Delete model Customer Relationship Management, 71, 139 Data Transfer Object pattern, 26 Data Transfer Services, 137 design pattern, 4, 139, see OSS Design Patterns Digital Subscriber Loop (DSL), 139 discovery pattern, see OSS Discovery pattern Distributed Management Task Force, 23 Element Management System, 8 Element Management System (EMS), 139 EMS, see Element Management System end-user application, 139 engagement style consistent, 13 Enterprise Java Beans, 8, 17 EJB 3.0, 37 enterprise management, 5 Entities.xsd, 112 EQUIPMENTTYPE, 31 equipment record, 22 EquipmentRecordValue, 31, 32, 50, 83, 97, 107 EquipmentRecordValueType, 84, 89, 98, 121, 123 event notification pattern, see OSS Event Notification pattern event notifications, 14, 72 execute(), 38, 72 extended equipment record, 22 ExtendedEquipmentRecordValue, 31, 32, 107 ExtendedEquipmentRecordValueType, 98 extension, 54 fac¸ade, see OSS Fac¸ade fac¸ade pattern, see OSS Fac¸ade pattern

Index factory pattern, see OSS Factory pattern federation, 75 formal query languages, 95 functional partitioning, 6 getInventoryRecordByKey, 39, 88, 93 getInventoryRecordByKey(), 19, 32, 38, 92 getInventoryRecordByKeyResponse, 89 getInventoryRecordsByTemplate(), 38, 50, 97 getInventoryRecordsByTemplateRequest, 51 getInventoryRecordsByTemplateResponse, 51 getManagedEntityTypes(), 38 getNext(n), 48, 49 getter, see accessor glossary, 139 ID, 76 implementation profile, 16, 139 independent software vendors, 3 information exchange rules for, 14 information model, 13, 19, 139 integration interface, 3, see OSS Interface integration layer, see OSS integration layer integration tax, vii interface categories, 16 interface design, 4 interface style, 4, 11 Internet Engineering Task Force, 23 introspection, 60 InventoryRecordValue, 30–32, 83, 107 InventoryRecordValueType, 52, 84, 89, 97, 98 InventorytRecordValue, 31 invocation overhead, 17 iterator, 68 iterator pattern, see OSS Iterator pattern IteratorNamedProcedure, 68 IteratorRequest, 51 IteratorResponse, 51 Java data types, 17 Java Message Service, 17, 19, 43, 46, 140 Java methods, 17 Java Platform, Enterprise Edition, 17, 140 Java-style API, 17 java.io.Serializable, 29 JAXB to implement a client, 121

Index JEE, see Java Platform, Enterprise Edition JMS, see Java Message Service key, 19 key lookup, 19 key pattern, see Managed-Entity Key pattern Last Update-Version-Number pattern, 104 LastUpdateVersionNumber, 30 layered functionality, see OSS Reference Model learning curve reducing, 13 life cycle pattern, see Managed-Entity Life Cycle pattern LOCATION, 31 Location, 92 location, 68, 93 locked records, 104 Long Term Evolution (LTE), 140 long-lived request, 71 makeInventoryRecordValue(), 38, 83 makeNamedProcedureValue(), 38 managed entity, 15, 19, 140 associative lookup, 19 attributes, 19 updating, 86 bulk updating of, 100 concurrent updating of, 104 creation and deletion of, 80 identifying, 19 implementation, 20, 26 key to, 19 name, 83 reference to, 75 referencing, 19 selection, 95 updating multiple, 100 managed resource, 3, 8, 15, 25, 95, 140 life cycle, 80 management, 19 modelling, 19 reference to, 75 state, 95 managed system, 3, 8, 140 managed-entity stale values in, 104 Managed-Entity Attribute Population pattern, 91 managed-entity attributes updating, 26 Managed-Entity Bulk Update pattern, 100 managed-entity create

147 example, 81 managed-entity delete example, 81 managed-entity key, 76 assignment, 76 Managed-Entity Key pattern, 13, 75 Managed-Entity Life Cycle pattern, 80 Managed-Entity Model, 13, 19 Managed-Entity Services, 137 Managed-Entity Template Filter pattern, 13, 95 Managed-Entity Update pattern, 86, 94 managed-entity value, 86, 91, 140 used to create a managed entity, 80 Managed-Entity Value pattern, 14, 25, 80, 85 ManagedEntityValue, 29–31, 107 ManagedEntityValueType, 33 management challenge, 3 Management Information Base, 13 Management Integration System, 2, 7, 140 management logic, 3 management problem, 12 management requirements, see telecommunications management requirements, 12 management solution, 3, 140 client-server style, 13 delivery, 2 deploying, 3 developing, 3, 11, 26 using patterns, 4 management solutions developing, 13 management system deployment, 1 overview, 1 management task, 2 management-integration application, 3, 13, 140 manual intervention, 71 message profile, see OSS Message Profile message-driven bean, 39 MessageListener, 43 messaging, 16 metadata, 36 MIB, see Management Information Base monitoring business systems, 41 equipment, 41 mutators, 28 NAME, 32 named-procedure pattern, see OSS Namedprocedure pattern NamedProcedure, 67, 68

148 Network Element (NE), 140 network latency, 100 notification service, 15, 140 notification signatures, 17, 19 notification style, 18 null, 92 NUMBERONHAND, 31 NumberOnHand, 92 numberOnHand, 93, 101 ObjectMessage, 43 onMessage(), 43, 72, 125 operation signatures, 16, 17, 19 Operations Support System, 3, 8 Operations Support System (OSS), 140 operator applications, 7 operator system, 2, 7, 140 operator-support application, 7, 13, 140 operator-support layer, 6, 7 OSS, see Operations Support System OSS application, 3, 15, 140 operational aspects, 36 OSS Application Context, 20 OSS application layer, 7 OSS Application Services, 137 OSS client, 13, 14, 141 OSS Command–Status pattern, 71 OSS Design Pattern, 141 OSS design pattern, 12 OSS Design Patterns, 20 interactions, 135 relationships, 135 usage, 137 OSS Discovery pattern, 58 OSS Event Notification pattern, 14, 41 use, 73 OSS Fac¸ade pattern, 36 OSS Fac¸ade, 14, 141 OSS Fac¸ade pattern, 13 OSS Factory pattern, 53, 81 OSS functionality discovery, 58 OSS Implementation Profiles, 14, 16 OSS Integration Interface, 6, 14 OSS integration interface, 141 OSS integration layer, 7 OSS interfaces brittle, 16 coupling, 16 performance, 16 OSS Iterator pattern, 48, 96 OSS Message Profile, 16, 18, 18, 141 OSS Named-procedure pattern, 14, 64, 99 use, 72

Index OSS Reference Architecture, 12, 14, 141 OSS Reference Model, 6, 12, 141 OSS Session Profile, 16, 17, 141 OSS Systems Architecture, 7 developing, 11 pattern, see design pattern pattern approach, 4 pattern interactions, see OSS Design Patterns pattern relationships, see OSS Design Patterns pattern usage, see OSS Design Patterns performance of interfaces, 16 polling, 41 polymorphism, 83, 85 populated attributes, 80 population pattern, see Manage-Entity Attribute Population pattern presentation layer, 6, 7 procedure call model, 17 programming pattern, 141 publish-and-subscribe model, 42 publish-and-subscribe style, 3, 14, 18 query mechanism, 14 QueryReorderItems, 68, 69 rapid development, 13 read-update model, 86 Record Type, 76 RecordCreateEvent, 43 RECORDID, 29 RecordKey, 28–30, 107 RecordKeyType, 33, 123 records, 68 RECORDTYPE, 29 reference model, 6, see OSS Reference Model referencing managed entities, 19 reliable implementation, 13 remote operations, 14, 15 Remote Operations Model, 14, 15 asynchronous mode, 16 synchronous mode, 16 Remote Procedure Call, 16 removeInventoryRecordByKey(), 38 REORDERLEVEL, 32 RPC, see Remote Procedure Call Service Oriented Architecture, 4 service providers, 3 service quality, 41 service-fulfillment application example, 11 service-level agreements, 1 session-oriented, 17

Index session-oriented data exchange, 141 sessionless data exchange, 141 setInventoryRecordByValue, 39, 40 setInventoryRecordByValue(), 38 setInventoryRecordsByValues, 102 setInventoryRecordsByValues(), 38, 101 setter, see mutator SID, see TM Information Framework Simple Inventory, 22 create record, 81 delete record, 81 interface declarations, 107 interface diagram, 27 key structure, 76 methods, 38, 111 operations, 39, 112 re-order example, 65 restoring database, 72 retrieving attributes, 91 update attribute values, 87 use of bulk update, 100 use of discovery pattern, 59 use of factory pattern, 55 use of iterator, 96 use of key, 76 XML definitions, 112 software architecture, 13, 141 stale values, 104 status, 20 String, 92 supplier record, 22 SUPPLIERNAME, 32 SupplierRecordValue, 32, 107 support resource, 3, 141 synchronous RPC style, 17 system integrators, 3 systems architecture, 7, 13, 141

149 technology binding, 15, 21 telecommunications management requirements, 5 telecommunications management system, 142 overview, 1 telecommunications service, 142 customers, 1 growth, 1 telecommunications-equipment vendors, 3 template, 95 template filter pattern, see Managed-Entity Template Filter pattern TextMessage, 45 thoughts final, 105 TM Business Process Framework, 5 TM Information Framework, 13 Toronto, 69 type definitions Simple Inventory, 107 type hierarchy, 85 type safety, 58 unPopulate(), 92 update pattern, see Managed-Entity Update pattern updating multiple managed entities, 100 value pattern, see Managed-Entity Value pattern value type, 142 passing, 53 Web Services, 4, 8, 19 XML document types, 19 XML Schema, 19, 142 use, 107 xsi:type, 47, 52, 84, 89, 98

Colophon

The text of this book was prepared in LATEX using TeXShop on a Macintosh Mac Pro computer. The Java and XML examples were collaboratively prepared on the same Mac Pro and a Windows computer both using NetBeans. The example code was extracted from the NetBeans files with Applescripts that look for speciallyformatted comments and then copy the code into the LATEX source file. The diagrams were prepared on the Mac Pro using Microsoft PowerPoint and CS Odessa ConceptDraw. The .pdf outputs of the programs were cropped using Mac Preview and placed in the appropriate locations for inclusion by TeXShop.

151