Data Definition Language Objectivity/C++ Data Definition Language Release 12.0 Objectivity/C++ Data Definition Language Part Number: 12.0-DDL-0 Release 12.0, May 6, 2016 The information in this document is subject to change without notice. Objectivity, Inc. assumes no responsibility for any errors that may appear in this document. Copyright 1993–2016 by Objectivity, Inc. All rights reserved. This document may not be copied, photocopied, reproduced, translated, or converted to any electronic or machine-readable form in whole or in part without prior written approval of Objectivity, Inc. Objectivity, Objectivity/DB, and InfiniteGraph are registered trademarks of Objectivity, Inc. Active Schema, Objectivity/DB Active Schema, Assist, Objectivity/Assist, ooAssistant, Objectivity/DB ooAssistant, Objectivity/DB Fault Tolerant Option, Objectivity/FTO, Objectivity/DB Data Replication Option, Objectivity/DRO, Objectivity/DB High Availability, Objectivity/HA, Objectivity/DB Hot Failover, Objectivity/DB In-Process Lock Server, Objectivity/IPLS, Objectivity/DB Open File System, Objectivity/OFS, Objectivity/DB Parallel Query Engine, Objectivity/PQE, Objectivity/DB Persistence Designer, Objectivity/DB Secure Framework, Objectivity/Secure, Objectivity/C++, Objectivity/C++ Data Definition Language, Objectivity/DDL, Objectivity/Dashboard, Objectivity/C++ Active Schema, Objectivity/C++ Standard Template Library, Objectivity/C++ STL, Objectivity/C++ Spatial Index Framework, Objectivity/Spatial, Objectivity for Java, Objectivity/.NET, Objectivity/.NET for C#, Objectivity/Python, Objectivity/Smalltalk, Objectivity/SQL++, Objectivity/SQL++ ODBC Driver, Objectivity/ODBC, Objectivity Event Notification Services, and Persistence Designer are trademarks of Objectivity, Inc. Other trademarks and products are the property of their respective owners. ODMG information in this document is based in whole or in part on material from The Object Database Standard: ODMG 2.0, edited by R.G.G. Cattell, and is reprinted with permission of Morgan Kaufmann Publishers. Copyright 1997 by Morgan Kaufmann Publishers. The software and information contained herein are proprietary to, and comprise valuable trade secrets of, Objectivity, Inc., which intends to preserve as trade secrets such software and information. This software is furnished pursuant to a written license agreement and may be used, copied, transmitted, and stored only in accordance with the terms of such license and with the inclusion of the above copyright notice. This software and information or any other copies thereof may not be provided or otherwise made available to any other person. RESTRICTED RIGHTS NOTICE: Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the Objectivity, Inc. license agreement and as provided in DFARS 227.7202-1(a) and 227.7202-3(a) (1998), and FAR 12.212, as applicable. Objectivity, Inc., 3099 North First Street, Suite 200, San Jose, CA 95134. Contents About This Book 9 Audience 9 Organization 9 Conventions and Abbreviations 10 Getting Help 11 Part 1 GUIDE Chapter 1 Getting Started 15 About Schema Development 15 Persistence-Capable Classes 16 Federated Database Schemas 16 Schema Development with Objectivity/DDL 17 Creating DDL Files 18 Basic DDL File Contents 18 Adapting Existing Header Files 18 Example: Adapting an Existing C++ Header File 20 Processing DDL Files 21 C++ Files Generated by the DDL Processor 22 Primary Header File 23 References Header File 24 Method Implementation File 24 Example: Including Generated Header Files 25 Treatment of Preprocessing Directives 27 Dependencies on DDL-Generated Code 27 3 Dividing Definitions Among Multiple Files 28 Obtaining Application-Specific Definitions 28 Obtaining Generated Class Definitions 31 Modifying the Schema 36 Adding to an Existing Schema 37 Replacing a Schema in Early Development 37 Summary 38 Chapter 2 Defining Persistence-Capable Classes 39 Data Definition Language 39 Making a Class Persistence-Capable 41 Multiple Inheritance 41 Class Templates 42 Limit on Class-Name Length 43 Namespaces 43 Defining the Component Data of a Class 45 Defining Attributes 45 Overview of Association Definition 57 Prohibited Data Types 58 Method Considerations 61 Avoiding Multiple Declarations 61 Redefining Inherited new Operators 61 Special-Purpose Constructor 61 Limitation on Destructors for Persistence-Capable Classes 64 Handling Unsupported C++ Features 65 Chapter 3 Defining Associations 67 About Associations 67 Association Directionality 68 Association Cardinality 69 Object Copying and Versioning 70 Propagating Operations 72 Association Storage Properties 73 Defining an Association 79 Basic Association Syntax 79 Inline Association Syntax 82 Requesting Propagation Operations 83 4 Objectivity/C++ Data Definition Language Specifying Object Copying and Versioning Behavior 84 Combining Behavior Specifiers 86 Association Syntax Summary 87 Unidirectional Associations 87 Bidirectional Associations 87 Behavior Specifiers 88 Chapter 4 Multiple Inheritance 89 Vehicle Object Model 90 Persistence through Inheritance 91 Object Modeling Using Root Persistence 91 Composite Objects and Root Persistence 93 Object Modeling Using Leaf Persistence 95 Enhanced Leaf Persistence 97 Mixing Root and Leaf Persistence 98 Chapter 5 Schema Evolution 101 About Schema Evolution 101 Schema-Evolution Operations 102 What You Can Change 103 Impact on Objects 103 Impact on Existing Applications 105 Impact on Performance 106 Schema-Evolution History 106 Schema Distribution 107 Performing Schema-Evolution Operations 107 Supported Schema-Evolution Operations 108 Setting Up a Development and Test Environment 109 Planning Schema Changes 110 Modifying Class Definitions 111 Processing Class Definitions 111 Capturing the Modified Schema for Distribution 113 Converting Objects 114 Modifying and Rebuilding Applications 116 Evolving Class Members 117 Adding Component Data to a Class 117 Deleting Component Data From a Class 120 Renaming Component Data in a Class 122 Objectivity/C++ Data Definition Language 5 Replacing Component Data in a Class 123 Changing the Properties of Component Data 126 Changing the Properties of Associations 133 Adding or Removing a Virtual Method 136 Evolving Classes 137 Adding a Class 137 Renaming a Class 137 Deleting a Class 138 Changing the Inheritance of a Class 142 Adding Persistence 153 Removing Persistence 154 Restructuring Classes 154 Distributing Schema Changes 158 Preparing for Distribution 159 Reproducing a Schema Operation 160 Deploying Updated Applications 160 Chapter 6 Class Versioning 163 About Class Versions 163 Class Versioning and Schema Evolution 164 Creating a New Version of a Class 164 Providing a Nickname for the Original Class 165 Creating the New Version 166 Using the Old and New Versions 168 Versioning Interrelated Classes 168 Preparing a Suitable DDL File 168 Nicknaming Multiple Classes in a DDL File 169 Versioning Multiple Classes in a DDL File 170 Chapter 7 Partitioning an Object Model 173 About Multiple Schemas 173 Adding Definitions to a Named Schema 175 Switching Between Multiple Schemas 176 6 Objectivity/C++ Data Definition Language Chapter 8 Schema Tuning 179 Tuning for Federated Database Size 179 Use Inline Associations 179 Store Data Efficiently 179 Tuning for Application Speed 182 Use Inline Associations 182 Part 2 REFERENCE Chapter 9 Tools 185 Chapter 10 DDL Pragmas 193 Part 3 APPENDIXES Appendix A Objectivity/C++ Include Files 205 Appendix B Schema Class Descriptions 207 About Schema Class Descriptions 207 Content of a Schema Class Description 207 Schema Class Names 208 Namespace and Package Qualifiers 208 Objectivity/DB Primitive Types 210 Mapping Objectivity/C++ Primitive Types 211 Mapping C++ Primitive Types 212 Objectivity/DB Primitive Types in Earlier Schemas 214 Appendix C Schema-Evolution Quick Reference 215 Index 219 Objectivity/C++ Data Definition Language 7 8 Objectivity/C++ Data Definition Language About This Book This book describes how to use the Objectivity/C++ Data Definition Language (DDL) and the DDL processing tool to develop a schema within an Objectivity/DB federated database. A schema defines the types of persistent objects you can store in a database. Audience This book assumes that you are familiar with the C++ programming language and with the Objectivity/C++ programming interface. Organization ■ Chapter 1 provides basic terminology, a simple example, and the steps for creating a schema from the class definitions in one or more DDL files. ■ Chapter 2 and Chapter 3 describe how to use the DDL to define persistence-capable classes and associations between them; Chapter 4 provides design guidelines when using multiple inheritance. ■ Chapter 5 and Chapter 6 describe two alternative ways of modifying an existing schema: schema evolution and versioning. ■ Chapter 7 and Chapter 8 describe mechanisms for organizing the definitions in a schema and techniques for tuning class definitions to promote efficient storage or faster access. ■ Chapter 9 and Chapter 10 contain reference information about the DDL processor and the pragma directives it accepts. ■ Appendix A is an overview of Objectivity/C++ header files. ■ Appendix B describes the Objectivity/DB primitive types that are specified in the schema for the corresponding Objectivity/C++ primitive types. ■ Appendix C is a quick reference of schema-evolution operations. 9 About This Book Conventions and Abbreviations Navigation In the online version of this book, table of contents entries, index entries, cross-references,