Oracle9i Data Cartridge Developer's Guide

Send Us Your Comments......Page 19 Preface......Page 21 New Features......Page 27 Part I Introduction......Page 31 1 What Is a Data Cartridge?......Page 33 What Are Data Cartridges?......Page 34 Why Build Data Cartridges?......Page 35 Data Cartridge Domains......Page 36 Extending the Server—Services and Interfaces......Page 38 Extensible Type System......Page 39 Collection Types......Page 40 Large Objects......Page 41 Extensible Server Execution Environment......Page 42 Extensible Indexing......Page 43 Extensible Optimizer......Page 45 Data Cartridge Interfaces......Page 46 The Structure of a Data Cartridge......Page 47 External Library Linkage Specification......Page 48 Installing a Data Cartridge......Page 49 2 Roadmap to Building a Data Cartridge......Page 51 Development Process......Page 52 Installation and Use......Page 54 Globals......Page 55 Files......Page 56 Deployment Checklist......Page 57 Need for Naming Conventions......Page 58 Unique Name Format......Page 59 Directory Structure and Standards......Page 60 Internal Versioning......Page 61 Internal Access......Page 62 Configuration......Page 63 Suggested Development Approach......Page 64 Part II Building Data Cartridges......Page 65 3 Defining Object Types......Page 67 Objects and Object Types......Page 68 Assigning an OID to an Object Type......Page 69 Object Comparison......Page 71 4 Methods: Using C/C++ and Java......Page 73 Using Shared Libraries......Page 74 Registering an External Procedure......Page 75 How PL/SQL Calls an External Procedure......Page 76 Configuration Files for External Procedures......Page 78 Specifying Datatypes......Page 79 Using the Parameters Clause......Page 81 OCIExtProcGetEnv......Page 82 Restrictions on Callbacks......Page 83 OCI Access Functions for External Procedures......Page 84 OCIExtProcRaiseExcpWithMsg......Page 85 Debugging External Procedures......Page 86 Guidelines for Using External Procedures with Data Cartridges......Page 87 Java Methods......Page 88 5 Methods: Using PL/SQL......Page 89 Implementing Methods......Page 90 Invoking Methods......Page 92 PL/SQL Packages......Page 93 Pragma RESTRICT_REFERENCES......Page 94 Privileges Required to Create Procedures and Functions......Page 95 Debugging PL/SQL Code......Page 96 Signature Mismatches......Page 97 Package Corruption......Page 98 6 Working with Multimedia Datatypes......Page 99 DDL for LOBs......Page 100 LOB Locators......Page 101 EMPTY_BLOB and EMPTY_CLOB Functions......Page 102 Using the OCI to Manipulate LOBs......Page 104 Using DBMS_LOB to Manipulate LOBs......Page 108 LOBs in External Procedures......Page 109 Using Open/Close as Bracketing Operations for Efficient Performance......Page 110 Errors and Restrictions Regarding Open/Close Operations......Page 111 7 Building Domain Indexes......Page 113 What is Indexing?......Page 114 The Need for Index Structures that Encompass Unstructured Data......Page 115 B-tree......Page 116 Hash......Page 117 k-d tree......Page 118 Point Quadtree......Page 120 Why is Extensible Indexing Necessary?......Page 121 The Extensible Indexing API......Page 122 Overview......Page 125 Example: A Text Indextype......Page 127 Creating Indextypes......Page 129 ODCI Index Interface......Page 130 Index Definition Methods......Page 131 Index Scan Methods......Page 132 Transaction Semantics during Index Method Execution......Page 134 Privileges During Index Method Execution......Page 135 Domain Index Operations......Page 136 Domain Indexes on Index-Organized Tables......Page 137 Export/Import of Domain Indexes......Page 139 Operator Bindings......Page 140 Creating operators......Page 141 Invoking Operators......Page 142 Operators and Indextypes......Page 143 Operators in the WHERE Clause......Page 144 Operators Outside the WHERE Clause......Page 147 Ancillary Data......Page 149 Dependencies......Page 152 Privileges......Page 153 Partitioned Domain Indexes......Page 154 Summary of Index States......Page 156 Table Operations That Affect Indexes......Page 157 ODCIIndex Interfaces for Partitioning Domain Indexes......Page 158 Domain Indexes and SQL*Loader......Page 159 8 Query Optimization......Page 161 Overview......Page 162 User-Defined Statistics......Page 164 User-Defined Selectivity......Page 165 Cost......Page 166 User-Defined Cost......Page 167 Defining Statistics, Selectivity, and Cost Functions......Page 168 User-Defined Statistics Functions......Page 170 User-Defined Selectivity Functions......Page 171 User-Defined Cost Functions for Functions......Page 173 User-Defined Cost Functions for Domain Indexes......Page 174 Column Statistics......Page 176 Domain Index Statistics......Page 178 Package Functions......Page 179 Default Selectivity......Page 180 Package Functions......Page 181 Default Cost......Page 182 How Statistics Are Affected by DDL Operations......Page 183 Predicate Ordering......Page 184 Parallel Query......Page 185 Performance......Page 186 9 Using Cartridge Services......Page 187 Cartridge Services — Introduction......Page 188 Service Calls......Page 189 Memory Services......Page 190 Maintaining Context......Page 191 Globalization Support......Page 192 Parameter Manager Interface......Page 193 Input Processing......Page 194 Parameter Storage and Retrieval......Page 195 String Formatting......Page 196 Part III Advanced Topics......Page 199 10 Design Considerations......Page 201 Nested Tables......Page 202 Choosing a Language in Which to Write Methods......Page 203 When to Callout......Page 204 Saving and Passing State......Page 205 Can Index Structures Be Stored in LOBs......Page 206 Multi-Row Fetch......Page 207 Weighing Cost and Selectivity......Page 208 Design for maintenance......Page 210 How to Write Portable Cartridge Code......Page 211 11 User-Defined Aggregate Functions......Page 213 The ODCIAggregate Interface: Overview......Page 215 Using a User-Defined Aggregate......Page 217 Parallel Evaluation of User-Defined Aggregates......Page 218 Handling Large Aggregation Contexts......Page 219 External Context and Parallel Aggregation......Page 220 User-Defined Aggregates and Materialized Views......Page 221 Reusing the Aggregation Context for Analytic Functions......Page 222 Example: Creating and Using a User-Defined Aggregate......Page 223 12 Pipelined and Parallel Table Functions......Page 227 Overview......Page 228 Table Functions......Page 229 Pipelined Table Functions......Page 230 Pipelined Table Functions with REF CURSOR Arguments......Page 231 Parallel Execution of Table Functions......Page 232 Implementation Choices for Pipelined Table Functions......Page 233 Implementing the Native PL/SQL Approach......Page 234 Pipelining Between PL/SQL Table Functions......Page 235 Start Routine......Page 236 Close Routine......Page 237 Querying Table Functions......Page 238 PL/SQL......Page 239 Performing DML Operations on Table Functions......Page 240 Inputting Data with Cursor Variables......Page 241 PL/SQL REF CURSOR Arguments to Java and C/C++ Functions......Page 242 Input Data Partitioning......Page 245 Input Data Streaming for Table Functions......Page 247 Parallelizing Creation of a Domain Index......Page 249 Transient and Generic Types......Page 251 Part IV Scenarios and Examples......Page 255 13 Power Demand Cartridge Example......Page 257 Feature Requirements......Page 258 Modeling the Application......Page 265 Sample Queries......Page 266 Queries and Extensible Indexing......Page 269 Queries Benefiting from Extensible Indexing......Page 270 Creating the Schema to Own the Index......Page 271 Creating the Object Type (PowerDemand_Typ)......Page 272 Defining the Object Type Methods......Page 273 Creating the Functions and Operators......Page 275 Creating the Indextype Implementation Methods......Page 278 Type Definition......Page 279 ODCIIndexCreate Method......Page 281 ODCIIndexDrop Method......Page 283 ODCIIndexStart Method (for Specific Queries)......Page 284 ODCIIndexStart Method (for Any Queries)......Page 286 ODCIIndexFetch Method......Page 288 ODCIIndexClose Method......Page 289 ODCIIndexInsert Method......Page 290 ODCIIndexDelete Method......Page 291 ODCIIndexUpdate Method......Page 292 ODCIIndexGetMetadata Method......Page 293 Creating the Indextype......Page 295 Creating the Statistics Table (PowerCartUserStats)......Page 296 Creating the Extensible Optimizer Methods......Page 297 Type Definition......Page 298 ODCIGetInterfaces Method......Page 299 ODCIStatsCollect Method (for PowerDemand_Typ columns)......Page 300 ODCIStatsDelete Method (for PowerDemand_Typ columns)......Page 302 ODCIStatsCollect Method (for power_idxtype Domain Indexes)......Page 304 ODCIStatsDelete Method (for power_idxtype domain indexes)......Page 305 ODCIStatsSelectivity Method (for Specific Queries)......Page 306 ODCIStatsSelectivity Method (for Any Queries)......Page 314 ODCIStatsIndexCost Method (for Any Queries)......Page 316 ODCIStatsFunctionCost Method......Page 318 Associating the Extensible Optimizer Methods with Database Objects......Page 319 Testing the Domain Index......Page 320 Creating and Populating the Power Demand Table......Page 321 Querying Without the Index......Page 323 Creating the Index......Page 324 Querying with the Index......Page 325 14 PSBTREE: An Example of Extensible Indexing......Page 333 Design of the indextype......Page 334 Functional Implementation of GT (GREATER THAN)......Page 335 Implementing the Index Routines......Page 336 Common Error Processing Routine......Page 347 Implementation Of The ODCIIndexInsert Routine......Page 348 Implementation of the ODCIIndexDelete Routine......Page 351 Implementation of the ODCIIndexUpdate Routine......Page 353 Implementation of the ODCIIndexStart Routine......Page 356 Implementation of the ODCIIndexFetch Routine......Page 361 Implementation of the ODCIIndexClose Routine......Page 364 Usage examples......Page 366 Explain Plan Output......Page 367 Part V Reference......Page 369 15 Reference: Cartridge Services Using Java......Page 371 File Installation......Page 372 Cartridge Services—Maintaining Context......Page 373 Methods......Page 374 CountException()......Page 375 CountException(String)......Page 376 InvalidKeyException()......Page 377 InvalidKeyException(String)......Page 378 16 Reference: Extensibility Constants, Types, and Mappings......Page 379 System Defined Constants......Page 380 ODCIIndexAlter Options......Page 381 ODCIArgDesc.ArgType Bits......Page 382 ODCIEnv.CallProperty Values......Page 383 ODCIIndexInfo.Flags Bits......Page 384 ODCIPredInfo.Flag Bits......Page 385 ODCIFuncInfo.Flags Bits......Page 386 ODCIQueryInfo.Flags Bits......Page 387 ODCIStatsOptions.Flags Bits......Page 388 ODCIStatsOptions.Options Bits......Page 389 ScnFlg (Function with Index Context) Values......Page 390 Status Values......Page 391 System Defined Types......Page 393 ODCIArgDesc......Page 394 ODCIArgDescList......Page 395 ODCIRidList......Page 396 ODCIColInfo......Page 397 ODCIColInfoList......Page 398 ODCIColStats......Page 399 ODCIColStatsList......Page 400 ODCICost......Page 401 ODCIEnv......Page 402 ODCIFuncInfo......Page 403 ODCIIndexInfo......Page 404 ODCIPredInfo......Page 405 ODCIIndexCtx......Page 406 ODCIObject......Page 407 ODCIObjectList......Page 408 ODCIPartInfo......Page 409 ODCIQueryInfo......Page 410 ODCIStatsOptions......Page 411 ODCITabStats......Page 412 ODCITableFunctionStats......Page 413 Mappings in Java......Page 414 Constants for ODCIFuncInfo.Flags......Page 415 Constants for ODCIEnv.CallProperty......Page 416 17 Reference: Extensible Indexing Interface......Page 417 Extensible Indexing — System Defined Interface Routines......Page 418 ODCIGetInterfaces......Page 419 ODCIIndexAlter......Page 420 ODCIIndexClose......Page 423 ODCIIndexCreate......Page 424 ODCIIndexDelete......Page 427 ODCIIndexDrop......Page 428 ODCIIndexExchangePartition......Page 430 ODCIIndexFetch......Page 431 ODCIIndexGetMetadata......Page 433 ODCIIndexInsert......Page 436 ODCIIndexMergePartition......Page 437 ODCIIndexSplitPartition......Page 438 ODCIIndexStart......Page 439 ODCIIndexTruncate......Page 442 ODCIIndexUpdate......Page 444 18 Reference: Extensible Optimizer Interface......Page 445 EXPLAIN PLAN......Page 446 Example......Page 447 User-Defined ODCIStats Functions......Page 449 ODCIGetInterfaces......Page 450 ODCIStatsCollect (Column)......Page 452 ODCIStatsCollect (Index)......Page 454 ODCIStatsDelete (Column)......Page 456 ODCIStatsDelete (Index)......Page 458 ODCIStatsFunctionCost......Page 460 ODCIStatsIndexCost......Page 461 ODCIStatsSelectivity......Page 464 19 Reference: User-Defined Aggregates Interface......Page 467 ODCIAggregateInitialize......Page 468 ODCIAggregateIterate......Page 469 ODCIAggregateMerge......Page 470 ODCIAggregateTerminate......Page 471 ODCIAggregateDelete......Page 472 ODCIAggregateWrapContext......Page 473 20 Reference: Pipelined and Parallel Table Functions......Page 475 ODCITableStart......Page 476 ODCITableFetch......Page 477 ODCITableClose......Page 479 SQL Declarations for C Implementation......Page 481 C Implementation of the ODCITable Methods......Page 484 Java Implementation......Page 492 Java Implementation of the ODCITable Methods......Page 493 Index......Page 499