home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / NextDeveloper / Headers / dbkit / DBQualifier.h < prev    next >
Encoding:
Text File  |  1992-05-06  |  3.7 KB  |  107 lines
  1. /*
  2. **      DBQualifier.h
  3. **      Database Kit, Release 3.0
  4. **      Copyright (c) 1992, NeXT Computer, Inc.  All rights reserved. 
  5. */
  6.  
  7. #import <objc/Object.h>
  8. #import <dbkit/protocols.h>
  9.  
  10. /*
  11. ** Both DBExpression and DBQualifier represent qualifications expressed in
  12. **  the underlying query language...they use a printf-style format string,
  13. **  in which strings, numbers, and other objects can be embedded by using
  14. **  %s, %d, %f, %@, or %p respectively.
  15. **
  16. ** As the format string is parsed, each whitespace delimited 'word' that
  17. **  begins with an alpha and contains only '.' or alphanumeric characters
  18. **  is sought as a named property of the entity -- if a property with a
  19. **  matching name is found, it is inserted in place of the string.  Example:
  20. **
  21. **    aProp = [database propertyNamed:"employee"];
  22. **   [[DBExpression alloc] initForEntity:aProperty fromDescription:"mgr.name"];
  23. **
  24. **  This expression is the equivalent of asking the database for:
  25. **
  26. **    [database propertyNamed:"employee.mgr.name"];
  27. **
  28. **  Of course, to make things more interesting, multiple properties can be
  29. **  combined...
  30. **
  31. ** These characters are treated as legal alphanumerics: "._$#"
  32. **
  33. ** Here are the legal substitution formats:
  34. **
  35. **  %s expects a (const char*) argument, which will be passed through (and
  36. **       possibly quoted by the database)
  37. **  %p expects a (const char*) argument, which will be resolved against the
  38. **       entity for this expression/qualifier as a property name.
  39. **  %d expects an (int) argument
  40. **  %f expects a (double/float) argument
  41. **  %@ expects an (id) argument -- valid objects are DBValue, DBExpression,
  42. **       DBQualifier, or anything that conforms with the DBExpressionValues
  43. **       protocol
  44. **  %% is a '%' passed through...
  45. **
  46. **  All of the id arguments are expected to respond to either expressionValue:
  47. **   or stringValue.
  48. **
  49. **     set1 = [[DBQualifier alloc] initForEntity:employeeEntity
  50. **                           fromDescription:"%p > %d", "name", aNumber];
  51. **     set2 = [[DBQualifier alloc] initForEntity:employeeEntity
  52. **                           fromDescription:"ID IN (45, 65 78)"
  53. **     [[DBQualifier alloc] initForEntity:employeeProp
  54. **                    fromDescription:"(%@ OR %@) AND %p LIKE 'JONES'",
  55. **                    set1, set2, "name"];
  56. **
  57. ** Objects that respond to the stringValue message can be plugged into both
  58. **  DBExpressions and DBQualifiers.  Their value will be retrieved whenever
  59. **  a query expression is generated -- this can be quite handy for user
  60. **  interace considerations, or any kind of "ad-hoc" interface.
  61. **
  62. ** Quoting can be handled manually in the description string, or through the
  63. **  judicious use of format strings. Expressions and other properties print
  64. **  as literals. %s and %' formats will be quoted as character constants,
  65. **  according to the rules of the underlying query language.
  66. **
  67. **     aProp = [aDatabase propertyNamed:"employee.mgr.dept.name"];
  68. **     [[DBQualifier alloc] initForEntity:ent
  69. **                          fromDescription:"%@ LIKE %s", aProp, aString];
  70. **
  71. **  in SQL would produce: WHERE dept.name LIKE 'theStringValue'
  72. */
  73. @interface DBQualifier : Object <DBExpressionValues>
  74. {
  75. @private
  76.   id _nameString;
  77.   id _entity;
  78.   id _tree;
  79.   id _private;
  80. }
  81.  
  82. + initialize;
  83.  
  84. - initForEntity:(id<DBEntities>)anEntity;
  85. - initForEntity:(id<DBEntities>)anEntity
  86.     fromDescription:(const unsigned char*)aDescription, ...;
  87. - copyFromZone:(NXZone*)z;
  88. - free;
  89.  
  90. - empty;
  91. - (BOOL)isEmpty;
  92. - addDescription:(const unsigned char*)aDescription, ...;
  93.  
  94. - setEntity:(id<DBEntities>)anEntity 
  95.     andDescription:(const unsigned char*)aDescription, ...;
  96.  
  97. - (id <DBEntities>)entity;
  98. - (const char*)name;
  99. - (BOOL)setName:(const char*)aName;
  100.  
  101. - read:(NXTypedStream*)ts;
  102. - write:(NXTypedStream*)ts;
  103.  
  104. @end
  105.  
  106.  
  107.