Changeset 57417

Timestamp:

04/07/08 16:38:19 (3 months ago)

Author:

ischommer

Message:

FEATURE Added getSearchQuery(), getObjectQuery(), getObjectsQuery(), getObjectRelationQuery() to RestfulServer?
FEATURE Added $totalSize to DataFormatter? to add useful output for pagination via "limit" and "offset" parameters
API CHANGE Removed RestfulServer?->search()
API CHANGE Changed output format for convertDataObjectSet() in XMLDataFormatter and JSONDataFormatter

Location:

modules/sapphire/branches/roa/api

Files:

• DataFormatter.php (modified) (2 diffs)
• JSONDataFormatter.php (modified) (1 diff)
• RestfulServer.php (modified) (6 diffs)
• XMLDataFormatter.php (modified) (1 diff)

modules/sapphire/branches/roa/api/DataFormatter.php

@@ -62 +62 @@
          */
         protected $outputContentType = null;
+        
+        /**
+         * Used to set totalSize properties on the output
+         * of {@link convertDataObjectSet()}, shows the
+         * total number of records without the "limit" and "offset"
+         * GET parameters. Useful to implement pagination.
+         * 
+         * @var int
+         */
+        protected $totalSize;
         
         /**
@@ -184 +194 @@
         
         /**
+         * @param int $size
+         */
+        public function setTotalSize($size) {
+                $this->totalSize = (int)$size;
+        }
+        
+        /**
+         * @return int
+         */
+        public function getTotalSize() {
+                return $this->totalSize;
+        }
+        
+        /**
          * Returns all fields on the object which should be shown
          * in the output. Can be customised through {@link self::setCustomFields()}.

modules/sapphire/branches/roa/api/JSONDataFormatter.php

@@ -91 +91 @@
                         if($item->canView()) $jsonParts[] = $this->convertDataObject($item);
                 }
-                return "[\n" . implode(",\n", $jsonParts) . "\n]";
+                $json = "{\n";
+                $json .= 'totalSize: ';
+                $json .= (is_numeric($this->totalSize)) ? $this->totalSize : 'null';
+                $json .= ",\n";
+                $json .= "items: [\n" . implode(",\n", $jsonParts) . "\n]\n";
+                $json .= "}\n";
+
+                return $json;
         }
         

modules/sapphire/branches/roa/api/RestfulServer.php

@@ -141 +141 @@
          * @return String The serialized representation of the requested object(s) - usually XML or JSON.
          */
-        protected function getHandler($className, $id, $relation) {
+        protected function getHandler($className, $id, $relationName) {
                 $sort = array(
                         'sort' => $this->request->getVar('sort'),
@@ -151 +151 @@
                 );
                 
+                $params = $this->request->getVars();
+                
                 $responseFormatter = $this->getResponseDataFormatter();
                 if(!$responseFormatter) return $this->unsupportedMediaType();
                 
+                // $obj can be either a DataObject or a DataObjectSet,
+                // depending on the request
                 if($id) {
-                        $obj = DataObject::get_by_id($className, $id);
+                        // Format: /api/v1/<MyClass>/<ID>
+                        $query = $this->getObjectQuery($className, $id, $params);
+                        $obj = singleton($className)->buildDataObjectSet($query->execute());
                         if(!$obj) return $this->notFound();
+                        $obj = $obj->First();
                         if(!$obj->canView()) return $this->permissionFailure();
 
-                        if($relation) {
-                                if($relationClass = $obj->many_many($relation)) {
-                                        $query = $obj->getManyManyComponentsQuery($relation);
-                                } elseif($relationClass = $obj->has_many($relation)) {
-                                        $query = $obj->getComponentsQuery($relation);
-                                } elseif($relationClass = $obj->has_one($relation)) {
-                                        $query = null;
-                                } elseif($obj->hasMethod("{$relation}Query")) {
-                                        // @todo HACK Switch to ComponentSet->getQuery() once we implement it (and lazy loading)
-                                        $query = $obj->{"{$relation}Query"}(null, $sort, null, $limit);
-                                        $relationClass = $obj->{"{$relation}Class"}();
-                                } else {
-                                        return $this->notFound();
-                                }
-
-                                // get all results
-                                $obj = $this->search($relationClass, $this->request->getVars(), $sort, $limit, $query);
-                                if(!$obj) $obj = new DataObjectSet();
+                        // Format: /api/v1/<MyClass>/<ID>/<Relation>
+                        if($relationName) {
+                                $query = $this->getObjectRelationQuery($obj, $params, $sort, $limit, $relationName);
+                                if($query === false) return $this->notFound();
+                                $obj = singleton($className)->buildDataObjectSet($query->execute());
                         } 
                         
                 } else {
-                        $obj = $this->search($className, $this->request->getVars(), $sort, $limit);
+                        // Format: /api/v1/<MyClass>
+                        $query = $this->getObjectsQuery($className, $params, $sort, $limit);
+                        $obj = singleton($className)->buildDataObjectSet($query->execute());
+
                         // show empty serialized result when no records are present
                         if(!$obj) $obj = new DataObjectSet();
@@ -186 +183 @@
                 
                 $this->getResponse()->addHeader('Content-Type', $responseFormatter->getOutputContentType());
-                
-                if($obj instanceof DataObjectSet) return $responseFormatter->convertDataObjectSet($obj);
-                else return $responseFormatter->convertDataObject($obj);
+
+                if($obj instanceof DataObjectSet) {
+                        $responseFormatter->setTotalSize($query->unlimitedRowCount());
+                        return $responseFormatter->convertDataObjectSet($obj);
+                } else {
+                        return $responseFormatter->convertDataObject($obj);
+                }
         }
         
@@ -203 +204 @@
          * @return DataObjectSet
          */
-        protected function search($className, $params = null, $sort = null, $limit = null, $existingQuery = null) {
+        protected function getSearchQuery($className, $params = null, $sort = null, $limit = null, $existingQuery = null) {
                 if(singleton($className)->hasMethod('getRestfulSearchContext')) {
                         $searchContext = singleton($className)->{'getRestfulSearchContext'}();
@@ -210 +211 @@
                 }
                 $query = $searchContext->getQuery($params, $sort, $limit, $existingQuery);
-
-                return singleton($className)->buildDataObjectSet($query->execute());
-        }
-
+                
+                return $query;
+        }
+        
         /**
          * Returns a dataformatter instance based on the request
@@ -356 +357 @@
         }
         
+        /**
+         * Gets a single DataObject by ID,
+         * through a request like /api/v1/<MyClass>/<MyID>
+         * 
+         * @param string $className
+         * @param int $id
+         * @param array $params
+         * @return SQLQuery
+         */
+        protected function getObjectQuery($className, $id, $params) {
+                return singleton($className)->buildSQL(
+                        "ID = {$id}"
+                );
+        }
+        
+        /**
+         * @param DataObject $obj
+         * @param array $params
+         * @param int|array $sort
+         * @param int|array $limit
+         * @return SQLQuery
+         */
+        protected function getObjectsQuery($className, $params, $sort, $limit) {
+                return $this->getSearchQuery($className, $params, $sort, $limit);
+        }
+        
+        
+        /**
+         * @param DataObject $obj
+         * @param array $params
+         * @param int|array $sort
+         * @param int|array $limit
+         * @param string $relationName
+         * @return SQLQuery|boolean
+         */
+        protected function getObjectRelationQuery($obj, $params, $sort, $limit, $relationName) {
+                if($relationClass = $obj->many_many($relationName)) {
+                        $query = $obj->getManyManyComponentsQuery($relationName);
+                } elseif($relationClass = $obj->has_many($relationName)) {
+                        $query = $obj->getComponentsQuery($relationName);
+                } elseif($relationClass = $obj->has_one($relationName)) {
+                        $query = null;
+                } elseif($obj->hasMethod("{$relation}Query")) {
+                        // @todo HACK Switch to ComponentSet->getQuery() once we implement it (and lazy loading)
+                        $query = $obj->{"{$relation}Query"}(null, $sort, null, $limit);
+                        $relationClass = $obj->{"{$relation}Class"}();
+                } else {
+                        return false;
+                }
+
+                // get all results
+                return $this->getSearchQuery($relationClass, $params, $sort, $limit);
+        }
+        
         protected function permissionFailure() {
                 // return a 401

modules/sapphire/branches/roa/api/XMLDataFormatter.php

@@ -97 +97 @@
                 $className = $set->class;
         
-                $xml = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<$className>\n";
+                $xml = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
+                $xml .= (is_numeric($this->totalSize)) ? "<$className totalSize=\"{$this->totalSize}\">\n" : "<$className>\n";
                 foreach($set as $item) {
                         if($item->canView()) $xml .= $this->convertDataObjectWithoutHeader($item);