# baseten / Sources / BaseTen.h

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 // // BaseTen.h // BaseTen // // Copyright (C) 2006-2008 Marko Karppinen & Co. LLC. // // Before using this software, please review the available licensing options // by visiting http://basetenframework.org/licensing/ or by contacting // us at sales@karppinen.fi. Without an additional license, this software // may be distributed only in compliance with the GNU General Public License. // // // This program is free software; you can redistribute it and/or modify // it under the terms of the GNU General Public License, version 2.0, // as published by the Free Software Foundation. // // This program is distributed in the hope that it will be useful, // but WITHOUT ANY WARRANTY; without even the implied warranty of // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the // GNU General Public License for more details. // // You should have received a copy of the GNU General Public License // along with this program; if not, write to the Free Software // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA // // $Id$ // #import #import #import #import #import #import #import #import #import /* * Helpful breakpoints: * * BXHandleError2 * BXAssertionDebug * bx_error_during_rollback * bx_error_during_clear_notification * bx_test_failed * pgts_unrecognized_selector * */ /** * \defgroup baseten BaseTen * BaseTen is linked to Foundation, CoreData, Security, IOKit and SystemConfiguration frameworks and * libcrypto, libssl and libstdc++ dynamic libraries. In addition, it is weakly linked to AppKit framework. * Therefore it can be used to develop applications that don't require the graphical user interface. */ /** * \defgroup descriptions Descriptions * \ingroup baseten * Database introspection. */ /** * \defgroup auto_containers Self-updating collections * \ingroup baseten * Collections updated by the database context. * The context will change the collection's contents according to its filter predicate * after each relevant modification to the database. */ /** * \mainpage Introduction * * BaseTen is an open source Cocoa database framework for working with PostgreSQL databases. BaseTen * has been designed with familiar, Core Data -like semantics and APIs. * * The BaseTen feature highlights include: * \li BaseTen Assistant imports Core Data / Xcode data models. * \li Discovers the database schema automatically at runtime, including 1-1, 1-many and many-many relationships. * \li Database changes are propagated to clients automatically, without polling. * \li In-memory database objects are uniqued, and objects fetched via relationships are faults by default. * \li Support for RDBMS features like database-driven data validation, multi-column primary keys and updateable views. * \li Autocommit and manual save/rollback modes, both with NSUndoManager integration. * \li A BaseTen-aware NSArrayController subclass automates locking and change propagation. * \li Fetches are specified with NSPredicates (the relevant portions of which are evaluated on the database). * * \sa \ref general_usage */ /** * \page general_usage Using BaseTen framework * * \li \subpage overview * \li \subpage accessing_values * \li \subpage getting_started * \li \subpage tracking_changes * \li \subpage using_appkit_classes * \li \subpage database_types * \li \subpage postgresql_installation * \li \subpage building_baseten * \li \subpage limitations */ /** * \page overview Overview of BaseTen * * \image html BaseTen-object-relationships.png "Relationships between BaseTen's objects" * \image html BaseTen-class-hierarchy.png "BaseTen class hierarchy" * \image latex BaseTen-object-relationships.pdf "Relationships between BaseTen's objects" width=\textwidth * \image latex BaseTen-class-hierarchy.pdf "BaseTen class hierarchy" width=\textwidth * * BaseTen aims to provide a Core Data -like API for handling a database. A database connection is managed * by an instance of BXDatabaseContext, which also fetches rows from the database. Rows are represented * by instances of BXDatabaseObject. Objects are identified by * \link BXDatabaseObjectID BXDatabaseObjectIDs\endlink, that are created using * tables' primary keys. Foreign keys are interpreted as relationships between objects. * * Like some other object-relational mappers, BaseTen fetches the data model from the database. * There are classes available for database introspection: BXEntityDescription, BXAttributeDescription, * BXRelationshipDescription and its subclasses. * * Database objects are retrieved using an instance of BXDatabaseContext. The rows are specified using * instances of BXEntityDescription and NSPredicate. This pattern should match most use cases. It is also * possible to fetch rows as NSDictionaries by specifying an SQL query. * * Unlike the typical use case of Core Data, multiple users might be connected to the database being * accessed using BaseTen. Thus, data manipulated with database objects could change at any time. BaseTen * copes with this situation by updating objects' contents as soon as other database clients commit their * changes. The other clients needn't use BaseTen. * * Instead of constantly polling the database for changes, BaseTen listens for PostgreSQL notifications. * It then queries the database about the notification type and faults the relevant objects. For this to * work, certain tables, views and functions need to be created in the database. The easiest way to do this * is to connect to the database with BaseTen Assistant. Using it, relations may be enabled for use with * the framework. Everything will be installed or will reference to a database schema called baseten, so * removal, if needed, will be an easy process. BaseTen can connect to databases without the schema, but * in this case functionality will be limited. * * Since BaseTen relies on database introspection, SQL may be used to define the database schema. * Another option is to create a data model using Xcode's data modeler and import it using BaseTen Assistant. * * \see \subpage predicates * \see \subpage sql_views * \see \subpage baseten_enabling */ /** * \page predicates Predicates * * Most types of predicates and expressions are converted to SQL and sent to the database server. * Others cause the returned object set to be filtered again on the client side. Specifically, the following * use cases work in this manner: The affected part of the predicate is replaced with \em true (or \em false, * if the part is inside an odd number of NOT predicates), and excess objects are removed from the result set * after it has been received. * *
*
• Use of NSDiacriticInsensitivePredicateOption
• *
• Use of NSCustomSelectorPredicateOperatorType
• *
• Use of NSSubqueryExpressionType
• *
• Use of NSUnionSetExpressionType
• *
• Use of NSIntersectSetExpressionType
• *
• Use of NSMinusSetExpressionType
• *
• A modifier other than NSDirectPredicateModifier in combination with any of the following: *
*
• NSBeginsWithPredicateOperatorType
• *
• NSEndsWithPredicateOperatorType
• *
• NSMatchesPredicateOperatorType
• *
• NSLikePredicateOperatorType
• *
• NSContainsPredicateOperatorType
• *
• NSInPredicateOperatorType
• *
*
• *
*/ /** * \page sql_views SQL views * * Contents of SQL views may be manipulated using database objects provided that some conditions are met. * Unlike tables, views don't have primary keys but BaseTen still needs to be able to reference individual * rows. If a view has a group of columns that can act as a primary key, the columns may be marked as a * primary key with the assistant, after which the view may be enabled. * * Views also lack foreign keys. Despite this entities that correspond to views may have relationships * provided that a certain condition is met: the view needs to have the column or columns of an underlying * table that form a foreign key, and the columns' names need to match. In this case, relationships will * be created between the view and the target table as well as the view and all the views that are based * on the target table and contain the columns the foreign key references to. This applies to the complete * view hierarchy. * * PostgreSQL allows INSERT and UPDATE queries to target views if rules have been created to handle them. * In this case, the view contents may be modified also with BaseTen. */ /** * \page baseten_enabling More detail on enabling relations * * Some tables are created in BaseTen schema to track changes in other relations. The association is based * on relation \em oids \ref baseten_enabling_ref_1 "¹". The BaseTen tables store values for the actual * relations' primary keys. Thus, changing tables' primary keys after having them enabled will not work. * Should this need to be done, first disable the relation, then alter the primary key and finally enable * the relation again. Renaming or otherwise altering relations should be possible, though. * * In addition to using BaseTen Assistant, it is possible to enable and disable tables with SQL functions. * The functions are baseten.enable and baseten.disable and they take an \em oid as an argument. * * Views' primary keys are stored in baseten.view_pkey. The table has three columns: \em nspname, * \em relname and \em attname, which correspond to the view's schema name, the view's name and each primary * key column's name respectively. They also make up the table's primary key. In addition to using * BaseTen Assistant, it is possible to determine a view's primary key by inserting rows into the table. * * Relationships and view hierarchies among other things are stored in automatically-generated tables. * These should be refreshed with the SQL function baseten.refresh_caches after all changes to views, * primary keys and foreign keys. BaseTen Assistant does this automatically. * *
*
1. \anchor baseten_enabling_ref_1 PostgreSQL assigns an \em oid to each relation. This does not imply that tables should be created WITH OIDS.
2. *
*/ /** * \page getting_started Getting started * * Typically accessing a database consists roughly of the following steps: *
*
• \subpage creating_a_database_context "Creating an instance of BXDatabaseContext"
• *
• \subpage connecting_to_a_database "Connecting to a database"
• *
• \subpage getting_an_entity_and_a_predicate "Getting an entity description from the context and possibly creating an NSPredicate for reducing the number of fetched objects"
• *
• \subpage performing_a_fetch "Performing a fetch using the entity and the predicate"
• *
• \subpage handling_the_results "Handling the results"
• *
Relationship names *
Relationship typeTarget relation kindAvailable names
One-to-many (inverse, from the foreign key's side)TableTarget table's name, foreign key's name
ViewTarget view's name
One-to-many (from the referenced side)TableTarget table's name, schema_table_foreignkey
ViewTarget view's name
One-to-one (from the foreign key's side)TableTarget table's name, foreign key's name
ViewTarget view's name
One-to-one (from the referenced side)TableTarget table's name, schema_table_foreignkey
ViewTarget view's name
Many-to-manyTableTarget table's name, name of the foreign key that references the target table
ViewTarget view's name
*
1. Load the BaseTen plug-in or palette.
2. *
3. Create a new nib file.
4. *
5. Drag a database context and an array controller from the BaseTen palette to the file.
6. *
7. Select the database context and choose Attributes from the inspector's pop-up menu.
8. *
9. Enter a valid database URI. *
*
• If autocommit is selected from the context settings, the changes will be propagated immediately and * undo affects most operations but not all. Otherwise, the context's -save: and -revert: methods * should be used to commit and rollback. Undo may be used between commits.
• *
*
10. *
11. Select the array controller and choose Attributes from the inspector's pop-up menu.
12. *
13. Enter a table name into the field. *
*
• The schema field may be left empty, in which case \em public will be used.
• *
• Please note that the table needs to be enabled for change observing. This can be * done using the Setup Application.
• *
*
14. *
15. Bind the Cocoa views to the controller.
16. *
17. Test the interface. The views should be populated using the database.
18. *
*/ /** * \page database_types Handled PostgreSQL types * * Composite types, domains and types not listed here are currently returned as NSData. * Array types are returned as NSArrays of the respective type or NSArrays of NSData objects. * * * Type conversion *
PostgreSQL typeCocoa type
aclitem(A private class)
bitNSData
boolNSNumber
bpcharNSString
byteaNSData
charNSString
dateNSCalendarDate\ref database_types_ref_1 "¹"
float4NSNumber
float8NSNumber
int2NSNumber
int2vectorNSArray of NSNumbers
int4NSNumber
int8NSNumber
nameNSString
numericNSDecimalNumber
oidNSNumber
pointNSValue
textNSString
timestampNSDate
timestamptzNSCalendarDate\ref database_types_ref_1 "¹"
varbitNSData
varcharNSString
uuidNSString
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
*
1. \anchor database_types_ref_1 Subject to change as NSCalendarDate might become deprecated.
2. *
*/ /** * \page postgresql_installation PostgreSQL installation * * Here's a brief tutorial on PostgreSQL installation. *
*
1. Get the latest PostgreSQL source release (8.2 or later) from http://www.postgresql.org/ftp/source.
2. *
3. Uncompress, configure, make, [sudo] make install. On Mac OS X, Bonjour and OpenSSL are available, so ./configure –-with-bonjour –-with-openssl && make && sudo make install probably gives the expected results.
4. *
5. It's usually a good idea to create a separate user and group for PostgreSQL, but Mac OS X already comes with a database-specific user: for mysql. We'll just use that and hope PostgreSQL doesn't mind.
6. *
7. Make \em mysql the owner of the PostgreSQL folder, then sudo to mysql:\n * * sudo chown -R mysql:mysql /usr/local/pgsql\n * sudo -u mysql -s * *
8. *
9. Initialize the PostgreSQL database folder. We'll use en_US.UTF-8 as the default locale:\nLC_ALL=en_US.UTF-8 /usr/local/pgsql/bin/initdb -D \\\n /usr/local/pgsql/data
10. *
11. Launch the PostgreSQL server itself:\n * * /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data \\\n * -l /usr/local/pgsql/data/pg.log start * *
12. Create a superuser account for yourself. This way, you don't have to sudo to mysql to create new databases and users.\n * /usr/local/pgsql/bin/createuser *
13. *
14. Exit the \em mysql sudo and create a database. If you create a database with your short user name, psql will connect to it by default.\n * * exit\n * /usr/local/pgsql/bin/createdb * *
15. *
*/ /** * \page building_baseten Building BaseTen * * For a successful build, Xcode 3.1 and Mac OS X 10.5 SDK are required. * * BaseTen has several subprojects, namely BaseTenAppKit and a plug-in for Interface Builder 3. The default target in * BaseTen.xcodeproj, BaseTen + GC, builds them as well; the plug-in and the AppKit framework will appear in the * subprojects' build folders, which are set to the default folder. The built files will be either in * \em build folders in the subprojects' folders or in the user-specified build folder. The documentation will be * in the \em Documentation folder. * * * \section building_for_the_release_dmg Building for the release disk image * * The files needed to build the release disk image are in the SVN repository as well. Doxygen is needed during * the process. To create the DMG, follow these steps: *
*
1. From the checked-out directory, cd ReleaseDMG.
2. *
3. The default location for the built files is BaseTen-dmg-build in the current directory. To set a custom path, edit the \em SYMROOT variable in create_release_dmg.sh.
4. *
5. * Do ./create_release_dmg.sh. The built DMG will appear in the \em ReleaseDMG folder. *
*
• If you don't have LaTeX installed, do ./create_release_dmg.sh -–without-latex instead. The PDF manual won't be included on the DMG, though.
• *
*
6. *
*/ /** * \page limitations Limitations in current version * * These are some of the most severe limitations in the current version. * \li Most public classes are non-thread-safe, so thread safety must be enforced externally if it's required. * Furthermore, all queries must be performed from the thread in which the context made a database connection. This could change * in the future, so it is best to create and handle a context only in one thread. * \li No serialization mechanism has been implemented for BXDatabaseObject. * \li Currently, migration models aren't understood by the assistant, so the easiest way to do model * migration might be using SQL. */