Using the Caché Objective-C Binding

Transcription

1 Using the Caché Objective-C Binding Version March 2014 InterSystems Corporation 1 Memorial Drive Cambridge MA

2 Using the Caché Objective-C Binding Caché Version March 2014 Copyright 2014 InterSystems Corporation All rights reserved. This book was assembled and formatted in Adobe Page Description Format (PDF) using tools and information from the following sources: Oracle Corporation, RenderX, Inc., Adobe Systems, and the World Wide Web Consortium at The primary document development tools were special-purpose XML-processing applications built by InterSystems using Caché and Java.,,,, Caché WEBLINK, and Distributed Cache Protocol are registered trademarks of InterSystems Corporation.,, InterSystems Jalapeño Technology, Enterprise Cache Protocol, ECP, and InterSystems Zen are trademarks of InterSystems Corporation. All other brand or product names used herein are trademarks or registered trademarks of their respective companies or organizations. This document contains trade secret and confidential information which is the property of InterSystems Corporation, One Memorial Drive, Cambridge, MA 02142, or its affiliates, and is furnished for the sole purpose of the operation and maintenance of the products of InterSystems Corporation. No part of this publication is to be used for any other purpose, and this publication is not to be reproduced, copied, disclosed, transmitted, stored in a retrieval system or translated into any human or computer language, in any form, by any means, in whole or in part, without the express prior written consent of InterSystems Corporation. The copying, use and disposition of this document and the software programs described herein is prohibited except to the limited extent set forth in the standard software license agreement(s) of InterSystems Corporation covering such programs and related documentation. InterSystems Corporation makes no representations and warranties concerning such software programs other than those set forth in such standard software license agreement(s). In addition, the liability of InterSystems Corporation for any losses or damages relating to or arising out of the use of such software programs is limited in the manner set forth in such standard software license agreement(s). THE FOREGOING IS A GENERAL SUMMARY OF THE RESTRICTIONS AND LIMITATIONS IMPOSED BY INTERSYSTEMS CORPORATION ON THE USE OF, AND LIABILITY ARISING FROM, ITS COMPUTER SOFTWARE. FOR COMPLETE INFORMATION REFERENCE SHOULD BE MADE TO THE STANDARD SOFTWARE LICENSE AGREEMENT(S) OF INTERSYSTEMS CORPORATION, COPIES OF WHICH WILL BE MADE AVAILABLE UPON REQUEST. InterSystems Corporation disclaims responsibility for errors which may appear in this document, and it reserves the right, in its sole discretion and without notice, to make substitutions and modifications in the products and practices described in this document. For Support questions about any InterSystems products, contact: InterSystems Worldwide Customer Support Tel: Fax: support@intersystems.com

3 Table of Contents About This Book Introduction Requirements The Caché Objective-C Binding First Steps Connecting the Binding to Caché Secure Connection Disconnecting Simple Example of Accessing a Sample Class Putting it All Together Compiling and Building Compiling SimpleExample with Xcode Setting up DYLD_LIBRARY_PATH Reference Release/Retain Rules Autorelease Pool Objects Creating a New Object Properties Key/Value Coding Key/Value Observing Methods Instance Methods Class Methods Queries Class Queries Dynamic SQL Transactions Error Checking and Debugging Debugging Objective-C Header Generator Command Line Tool Generating Headers Programmatically Getting a Stack Trace from an NSException Include the ExceptionHandling Framework Enable Stack Traces Decoding the Stack Trace Do Not in Your Application Using the Caché Objective-C Binding iii

4

5 About This Book The Caché Objective-C binding is implemented in Objective-C and Objective-C++, and utilizes the Caché C++ binding and the underlying ODBC driver as a transport. It is packaged as an Apple framework that can either be embedded into the Cocoa application bundle or installed in one of the Apple framework directories. Who This Book Is For In order to use this book, you should be reasonably familiar with Mac OS X and have some experience with Objective-C. Organization of This Book This book is organized as follows: The chapter Introduction describes the system requirements and architecture of the Objective-C binding. The chapter First Steps gives step by step instructions for writing and compiling an Objective-C binding application. The chapter Reference provides a reference for the behavior of the Objective-C binding. The chapter Error Checking and Debugging describes various tools and procedures that may help you to find or avoid problems in your Objective-C applications. Related Information The following Caché language bindings are also available for use on most operating systems: Using C++ with Caché Using Java with Caché Using the Caché Objective-C Binding 1

6

7 1 Introduction For a Mac OS X developer these days, the toolset of choice is the excellent Apple Xcode development environment, along with the Cocoa framework and Objective-C. While Xcode used to support other languages (such as Java), Apple has recently disclosed that Objective-C is the language of choice for Cocoa and Mac development, and that Cocoa-Java support will likely be dropped. The goal of the Objective-C binding is to bring the power and ease of Caché objects to Mac developers in their familiar Cocoa-Objective-C environment. 1.1 Requirements In order to make use of the Objective-C binding for Caché, you need a Mac (either Intel or PowerPC) running Mac OS X 10.4 (Tiger) (or later) and a copy of Xcode 2.2 (or later) installed. Xcode is available either on the OS install CD or as a free download from the Apple Developer Connection (registration required). For Intel/Mac development, you will want to ensure that you have at least version You will also need to have a copy of Caché 5.1 (or later) installed on your system, as well as a copy of the Objective-C binding itself. 1.2 The Caché Objective-C Binding The Caché Objective-C binding is implemented in Objective-C, Objective-C++, and utilizes the C++ binding and the underlying ODBC driver as a transport. It is packaged as an Apple framework that can either be embedded into the Cocoa application bundle or installed in one of the Apple framework directories (such as /Library/Frameworks or ~/Library/Frameworks). The binding projects objects dynamically, that is, there is no requirement for a code generator to generate projection classes to the local language (although such a tool does exist which can help cut down on runtime errors). Any registered Caché objects can be utilized via the Objective-C binding; all class methods, stored procedures, and queries can also be called; and, in addition, dynamic SQL queries can be executed. The Objective-C binding framework is built as a Universal Binary, which means it can be deployed and run on both PowerPCand Intel-based Macs. Using the Caché Objective-C Binding 3

8

9 2 First Steps The first step to using the Caché Objective-C binding is to create a project, either a command line, pure Objective-C program (or library framework) or a GUI Cocoa Application in Xcode. In either case, you will need to ensure that you have the framework specified in the link options (using -framework or by adding the Caché Objective-C binding to the Xcode project) and that your Objective-C source files also include the framework headers: #import <ObjectiveCache/ObjectiveCache.h> 2.1 Connecting the Binding to Caché The next step is to create a connection between the Objective-C binding and a host Caché system. This follows the model established by the C++ binding in that the connection is separated from the logical // First, connect to Cache ISCConnection* conn = [[ISCConnection alloc] init:@" [1972]:samples" user:@"_system" passwd:@"sys"]; ISCDatabase* db = [[ISCDatabase alloc] (NSException* localexception) NSLog(@"Connection failed: %@", localexception); We always want to wrap calls to the Objective-C binding blocks so that the binding will always raise an NSException upon encountering an error Secure Connection A secure connection can be made using the -init:principal:level // First, connect to Cache ISCConnection* conn = [[ISCConnection alloc] init:" [1972]:samples" principal:@"abc" level:99]; ISCDatabase* db = [[ISCDatabase alloc] (NSException* localexception) NSLog(@"Connection failed: %@", localexception); Once connected, the Objective-C binding can be used as described later. Using the Caché Objective-C Binding 5

10 First Steps Disconnecting The database object must be destroyed before the disconnect method is called. For example: [db release]; [conn disconnect]; The database has a reference to the connection object, which will cause the physical connection to be kept alive even after the connection object goes out of scope. If you release the database object and then the connection object, they disconnect for themselves. If you disconnect while still using the binding, you get errors! 2.2 Simple Example of Accessing a Sample Class The following simple example demonstrates how the Objective-C binding can be used to access one of the sample classes provided with Caché in the SAMPLES /* Next, open an existing instance of the Sample.Person object and then we retrieve a couple of values. */ obj = [db openid:@"sample.person" ident:@"101"]; if (nil = obj) NSString* cls = [obj get_classname]; NSString* name = [obj Name]; int age = [obj Age]; NSDate* dob = [obj (NSException* localexception) NSLog(@"Connection failed: %@", localexception); Values can be updated and saved in a similar manner: [obj setname:@"jobs,steven"]; [obj _Save:1]; Instance methods can be called very easily: int answer = [obj Addition:1 :2]; Putting it All Together To generate the header files for the Caché classes, run the following commands from the framework/commands directory: Run:./objc_generator -u_system -psys -s [1972]:samples Sample.Person Run:./objc_generator -u_system -psys -s [1972]:samples Sample.Address Here is the code all put together, along with the boiler plate Objective-C code that you would need to set up an autorelease pool. Cocoa applications get an autorelease pool from the main run loop, so setting one up is not necessary unless you are creating a new thread. 6 Using the Caché Objective-C Binding

11 Simple Example of Accessing a Sample Class /* -*- ObjC -*- * * Copyright (c) 2006 InterSystems, Corp. * Cambridge, Massachusetts, U.S.A. All rights reserved. * Confidential, unpublished property of InterSystems. * * SimpleExample.m: Objective-C binding simple example * */ #import <ObjectiveCache/ObjectiveCache.h> #import "Sample_Person.h" #import "Sample_Address.h" /*! * Create a new person object */ NSString* CreatePerson(ISCDatabase* db) NSAutoreleasePool* pool = [[NSAutoreleasePool alloc] init]; // First, we will create a new person Sample_Person* obj = [db create:@"sample.person"]; NSLog(@"Created an instance of %@", [obj get_classname]); // Now, we populate it [obj setname:@"jobs,steve"]; [obj setdob:[nsdate datewithstring:@" :00: "]]; [obj setssn:@" "]; Sample_Address* addr = [obj Office]; [addr setstreet:@"1 Infinite Loop"]; [addr setcity:@"cupertino"]; [addr setstate:@"ca"]; [addr setzip:@"95014"]; // And save... [obj _Save:1]; NSString* objid = [[obj _Id] retain]; NSLog(@"Saved as id %@", objid); // The Objective-C binding returns autoreleased objects, so we // do not need to release anything. [pool release]; return [objid autorelease]; /*! * Display a person object */ void ShowPerson(ISCDatabase* db, NSString* objid) // Open the object: Sample_Person* obj = [db openid:@"sample.person" ident:objid]; if (nil!= obj) NSString* cls = [obj get_classname]; NSString* name = [obj Name]; int age = [obj Age]; NSDate* dob = [obj DOB]; NSLog(@"Object(%@/%@), Name = %@, Age = %d, DoB = %@", objid, cls, name, age, dob); // Or we could just do this and call an instance method [obj PrintPerson]; else NSLog(@"Person %@ not found!", objid); Using the Caché Objective-C Binding 7

12 First Steps /*! * Delete a person object */ void DeletePerson(ISCDatabase* db, NSString* objid) Sample_Person* clsproxy = [db openclass:@"sample.person"]; [clsproxy _DeleteId:objid :-1]; NSLog(@"Deleted person id %@", objid); /** * Main entry point for unit tests * argc Number of arguments argv Argument vector Exit code for this process */ int main(int argc, char** argv) NSAutoreleasePool* pool = [[NSAutoreleasePool alloc] NSString* server NSString* user NSString* passwd ISCConnection* conn = [[ISCConnection alloc] autorelease]; ISCDatabase* db = [[ISCDatabase alloc] autorelease]; [conn init:server user:user passwd:passwd]; [db initwithconnection:conn]; NSLog(@"Connected to: %@ as %@", server, user); NSString* objid = CreatePerson(db); ShowPerson(db, objid); DeletePerson(db, (NSException* localexception) NSLog(@"SimpleExample failed: %@", localexception); [pool release]; return 0; Compiling and Building The simple example SimpleExample.m can be compiled from a shell script or makefile with a command similar to the following: gcc -framework AppKit -framework ObjectiveCache -L/Library/Frameworks/ObjectiveCache.framework/Libraries -o./simpleexample SimpleExample.m where the -F and -L options specify that the ObjectiveCache framework was installed in /tmp/frameworks. -fnext-runtime and -fobjc-exceptions are default values and can be omitted. -L for libraries seems to be mandatory Compiling SimpleExample with Xcode In order to compile and run this example using Xcode you may need to do the following: In Xcode Project Settings, adjust Other Linker Flags to be: 8 Using the Caché Objective-C Binding

13 Simple Example of Accessing a Sample Class -framework ObjectiveCache -framework AppKit -L/Library/Frameworks/ObjectiveCache.framework/Libraries In the Project window select Executables > (your executable name) select Menu File > Get Info select the Arguments tab add the following variable to the environment: DYLD_LIBRARY_PATH=/Library/Frameworks/ObjectiveCache.framework/Libraries Setting up DYLD_LIBRARY_PATH If the framework is not installed in a standard location (such as /Library/Frameworks, ~/Library/Frameworks), then DYLD_LIBRARY_PATH needs to be set so that Mac OS X can find the ODBC and C++ libraries at runtime: export DYLD_LIBRARY_PATH=$LOCATION_OF_OBJECTIVECACHE_FRAMEWORK/Libraries where the variable LOCATION_OF_OBJECTIVECACHE_FRAMEWORK is set to the location of the ObjectiveCache framework directory. In Xcode, set DYLD_LIBRARY_PATH in the executable's properties page as follows: Go to Xcode > Groups & File > Executables double click the executable or "get info" select the Arguments tab Add the following variables in the environment: Name Value DYLD_LIBRARY_PATH LOCATION_OF_OBJECTIVECACHE_FRAMEWORK/Libraries Using the Caché Objective-C Binding 9

14

15 3 Reference This section provides a reference for the behavior of the Caché Objective-C binding. 3.1 Release/Retain Rules As with the standard Objective-C language rules for release/retain, the Objective-C binding always returns autoreleased objects, with the exception of any cases where you explicitly call alloc (for example, when constructing the ISCDatabase and ISCConnection objects). In these cases, you are responsible for explicitly releasing them or autoreleasing them Autorelease Pool As with any Objective-C application, you need to have an autorelease pool set up. For Cocoa applications, the main run loop sets one up for the main thread. For any additional threads you create, you need to explicitly create a pool, as follows: NSAutoreleasePool* pool = [[NSAutoreleasePool alloc] init]; And when you are done: [pool release] If you are working in a loop, or under any other condition that can cause a large number of objects to be created, you should ensure that the memory is not released until you release the pool. For example, you may wish to use a nested autorelease pool inside a loop to prevent a buildup of unreleased memory. 3.2 Objects Any registered Caché object can be accessed via the Caché Objective-C binding. Broadly speaking, there are three main types of objects: Registered: An object that can be created and has an _instance_. Persistent: An object opened from the database (also registered). Serial: A persistent object that has no identity of its own; it is always embedded in another (usually persistent) object. In general, objects are brought into being in one of three ways: Using the Caché Objective-C Binding 11

16 Reference Creating Opening Swizzling Swizzled objects are brought into scope by referencing a property in another object or by calling a method and getting back an object from it Creating a New Object A new instance of an object, be it registered or persistent, can be created as follows, which essentially invokes the class method =%New()= on the specified class and returns the reference: id obj = [db create:@"sample.person"]; The object properties are set to their initial expressions; you may now set properties, get properties, call methods. The returned object is autoreleased, which means that it goes out of scope when the current autorelease pool is released. At this point, if the object has not been saved (in the case of a persistent object), then the changes will be lost. Some classes allow a parameter to be passed to the =%OnNew()= method via the call to %New, you can use -create:argument to invoke this: id obj = [db create:@"sample.person" argument:@"an argument"]; The actual argument depends on the class that you are creating Persistent Objects A persistent object can be opened from the database, using a database id as follows: id obj = [db openid:@"sample.person" ident:@"101"]; This particular example would open the instance of Sample.Person with the ID 101. As with registered objects, any changes that you make are lost once the object is autoreleased, unless you save them, as follows: [obj _Save:1] This invokes %Save with a parameter of 1, which indicates a deep save. A shallow save (meaning just save the immediate object instance of obj) would be invoked by passing 0 (zero) to -_Save. 3.3 Properties Properties can be set and fetched via the Caché Objective-C binding, using the following patterns: NSString* name = [obj Name]; And to set a property: [obj Name:@"Jobs,Steve"]; Once a persistent object has been modified, it must be saved via a call to -_Save: or the changes are lost. If you attempt to set a calculated (read-only) property, an NSException is raised with the appropriate error from the Caché server. 12 Using the Caché Objective-C Binding

17 Methods Key/Value Coding The Caché Objective-C binding also supports Key/Value Coding (KVC), which is heavily utilized by the Cocoa Bindings. This means that you can bind UI controls directly to instances of Caché objects. This is a very powerful feature that can save many thousands of lines of coding Key/Value Observing In addition to Key/Value Coding, the Caché Objective-C binding also supports Key/Value Observing, which allows you to register observers for changes made to Caché objects that are currently _open_. Again, coupled with Cocoa bindings, this allows for powerful and flexible UIs to be easily built. 3.4 Methods The Caché Objective-C binding allows for both instance and class method to be invoked from the Objective-C application to the Caché server Instance Methods Once you have an open object, you can invoke an instance method as if it were an Objective-C method. For multiple parameters, the additional parameters are unnamed. You just need supply the : (colon) placeholder. For example: int answer = [obj Addition:1 :2]; Class Methods Since class methods do not require an instance of a class to be invoked, but in the Caché Objective-C binding we need a context in which to invoke a class method, we introduce the notion of a _class proxy_. A class proxy is essentially the same as the normal object proxies, except that there are no properties or instance methods. Only class methods and class queries can be called. id proxy = [db openclass:@"sample.person"]; [proxy PrintPerson]; You can also use a regular instance object to invoke a class method. 3.5 Queries Class Queries There are two means by which class queries can be invoked. Either directly against the ISCDatabase object or via a class proxy object (see previous section on calling Class Methods). Using a Class Proxy A class query can be easily called against a class proxy or, indeed, an open object instance: Using the Caché Objective-C Binding 13

18 Reference id proxy = [db openclass:@"sample.person"]; id query = [proxy ByName:@"Jobs"]; int row = 0; [query execute]; while ([query fetch]) NSLog(@"Row %d: %@", ++row, [query stringvalueatindex:1]); Against the ISCDatabase Object It is also possible to invoke a class query directly against the ISCDatabase instance, although you need to individually bind each parameter: id query = [db prepare:@"sample.person" procedure:@"byname"]; int row = 0; [query setstring:@"jobs"]; [query execute]; while ([query fetch]) NSLog(@"Row %d: %@", ++row, [query stringvalueatindex:1]); Once you have acquired the query object, the traversal mechanism is exactly the same Dynamic SQL A Dynamic SQL query can be invoked against the ISCDatabase object using the -prepare: method; any parameters can then be bound before invoking the query: id query = [db prepare:@"select * FROM SAMPLE.PERSON WHERE NAME %STARTSWITH?"]; int row = 0; [query setstring:@"jobs"]; [query execute]; while ([query fetch]) NSLog(@"Row %d: %@", ++row, [query stringvalueatindex:1]); 3.6 Transactions The Caché Objective-C binding gives you complete control over transactions via a set of four functions defined in ISC- Database: -(void)transactionstart; -(void)transactioncommit; -(void)transactionrollback; -(int)transactionlevel; You can use these functions to wrap up any database operations (object operations or direct SQL) in transactions that can be committed or rolled back as desired. Transactions can also be nested. 14 Using the Caché Objective-C Binding

19 4 Error Checking and Debugging 4.1 Debugging The Caché Objective-C binding provides a mechanism for better understanding what is going on under the hood when things go wrong. A flag, ISCDebugLevel can be used to specify different levels of debug logging to the console (via NSLog). ISCDebugLevel can either be set by setting the environment variable ISCDebugLevel, or by setting the global int variable ISCDebugLevel (defined in ObjectiveCache.h) to an integer between 0 and 5. The higher the level, the more verbose the debug information. The levels are defined as: ISC_DEBUG_ALWAYS ISC_DEBUG_WARNING ISC_DEBUG_INFO ISC_DEBUG_FINE ISC_DEBUG_FINER ISC_DEBUG_FINEST Log always Log warnings only Log information Log fine level debug information Log fine level debug information Log fine level debug information In general, setting ISCDebugLevel to 0 (zero) will shut off all logging (except for anything at ISC_DEBUG_ALWAYS). Although setting the environment variable ISCDebugLevel only takes effect before the process is started, you can modify the global variable ISCDebugLevel on the fly and it will have immediately effect. 4.2 Objective-C Header Generator While the Caché Objective-C binding is completely dynamic, it is often desirable to be able to generate Objective-C headers from Caché classes. This can be done either via a command line tool shipped as part of the framework, or programmatically by calling a method on ISCDatabase Command Line Tool The framework has a command line header generator tool that can be used to generate Objective-C.h files from Caché classes on the server. It is tucked it into the framework directory: Using the Caché Objective-C Binding 15

20 Error Checking and Debugging./ObjectiveCache.framework/Commands/objc_generator It can be invoked as follows: objc_generator [<option>...] <classes...> Where <classes> is a list of classes separated by spaces. The options are as follows: -d Generate dependent classes -f Force generation of the header files -o dir Generate headers into the specified directory -s Connect to the specified Cache' server (e.g [1972]:SAMPLES) -u User to connect as -p Password By default, unless the -f option is given, the generator will only update the target.h file if it has really changed (thus preventing unnecessary source control updates). Also, no unnecessary date/time/version information is generated in the header Generating Headers Programmatically There may be cases where it is desirable to be able to generate headers from an Objective-C program, for example perhaps an Xcode plugin. The framework exposes a method to do this, implemented in the ISCDatabase class: - (NSDictionary*)Database generateheaders:(nsarray*)classes dependents:(bool)yn When called, this returns an NSDictionary of strings keyed by class names, where the class names correspond to the list of classes headers were requested for using the NSArray "classes" parameter. If dependents is specified as YES, then it will also generate headers for dependent classes. The strings stored in the NSDictionary are the actual header files, suitable for writing out to disk. 4.3 Getting a Stack Trace from an NSException Whenever your application gets an NSException, there is a way by which you can extract a stack trace from it for diagnostics/debugging purposes. There are a couple of steps required: Include the ExceptionHandling Framework You will need to add a #import in your Objective-C sources: #import <ExceptionHandling/NSExceptionHandler.h> For a console application, you will need to add: -framework ExceptionHandling For a Cocoa application, you will need to add the ExceptionHandling framework (found in /Library/Frameworks) to your Xcode project Enable Stack Traces Adding the following line of code to your =main()=, ideally this will be the first line of code executed, will ensure that stack traces get logged for all NSExceptions that are raised. 16 Using the Caché Objective-C Binding

21 Getting a Stack Trace from an NSException [[NSExceptionHandler defaultexceptionhandler] setexceptionhandlingmask:nslogandhandleeveryexceptionmask]; Decoding the Stack Trace Once stack traces have been enabled, they are accessible via the userinfo part of the NSException object. NSString* stk = [[exception userinfo] objectforkey:nsstacktracekey]; You can utilize the command line tool =atos(1)= to convert the hex exception values into a meaningful stacktrace as follows: /*! * Print a stack trace for the given exception. The stack trace is displayed * on stdout. */ void PrintStackTrace(NSException* exception) NSString* stk = [[exception userinfo] objectforkey:nsstacktracekey]; NSTask* ls = [[NSTask alloc] init]; NSString* pid = [[NSNumber numberwithint:getpid()] stringvalue]; NSMutableArray* args = [NSMutableArray arraywithcapacity:20]; [args addobject:@"-p"]; [args addobject:pid]; [args addobjectsfromarray:[stk componentsseparatedbystring:@" "]]; // NOTE: function addresses are separated by double spaces, not a single // space. [ls setlaunchpath:@"/usr/bin/atos"]; [ls setarguments:args]; [ls launch]; [ls waituntilexit]; [ls release]; Do Not in Your Application Although keyword is part of the new exception handling logic in Objective-C, exceptions thrown with it do not have a stack trace. If your application needs to throw its own exceptions, you should use -[NSException raise] instead: NSException* exception = [NSException exceptionwithname:@"nsgenericexception" reason:@"this is an exception!" userinfo:nil]; [exception raise]; Using the Caché Objective-C Binding 17

22