Return Type of GalleryStatus::sucess()

alexisb
alexisb's picture

Joined: 2005-11-24
Posts: 56
Posted: Sat, 2005-12-31 07:19

Hi, in many classes, for example GalleryModule.class, I see code such as:

return array(GalleryStatus::success(), array());

I can see the method is returning an array of arrays, however I'm not too sure about the type of GalleryStatus::success(), I've reviewed the code of the success() method in GalleryStatus.class and I feel a little more confused, here it is:

    /**
     * Return a success status
     *
     * @return object GalleryStatus a successful status
     * @staticvar GalleryStatus $success An object stating that everything went well
     * @static
     */
    function success() {

        /*
         * Use a static singleton for the success object, so that we don't have
         * to construct new objects needlessly.
         */
        static $success;
        if (empty($success)) {
            $success = new GalleryStatus(GALLERY_SUCCESS);
        }
        return $success;
    }

I even read about the singleton design pattern in the Gang of Four book and some websites but I still don't get it, could anybody please explain this code and the correct way of interpreting: return array(GalleryStatus::success(), array()) ?

Thanks!

Alexis Bellido - Ventanazul web solutions
 
valiant

Joined: 2003-01-04
Posts: 32509
Posted: Sat, 2005-12-31 13:50

GalleryStatus::success() returns a GalleryStatus object.

so when you see
* @return object GalleryStatus
somewhere, we expect that a function returns a status.

the status object can then be checked, e.g. with
if ($ret->isError()) {
print $ret->getAsHtml();
}

whether it's an error or a success, we expect almost everywhere to know what happened in the API / function / method calls. we can create error stacks etc. from it and do proper clean-up if something went wrong.

if a function returns:
return array(GalleryStatus::success(), array())
then the code that calls this function should be:
list ($ret, $results) = somefunction();
if ($ret->isError()) {
// return $ret->wrap(....);
}

so return array(GalleryStatus::success(), array())
returns an array of a status object that signals that everything went fine and the actual result of the function was an empty array().

why don't we use:
return array(new GalleryStatus('success'), array())
or something like that? because it would be slower. our singleton method creates a single success object which is reused everytime we need a success status.

in G2.1, we'll change this pattern slightly and success will be replaced by null, to make it even faster.
instead of
return array(GalleryStatus::success(), array())
you'll write
return array(null, array())
and the calling function will check
if ($ret) {
instead of
if ($ret->isError()) {
and only in case of an error, you'll actually create / deal with GalleryStatus objects.
note that we'll document this before G2.1 is out and there are even convert scripts where you can run your code through such that you don't have to change your code yourself.
 
alexisb
alexisb's picture

Joined: 2005-11-24
Posts: 56
Posted: Sat, 2005-12-31 16:31

Hi Valiant, thank you very much for your explanation.

It's clearer now, I think my confusion started with the return statement returning two different types, I am used to seeing (pseudo code follows):

return $aIntegerVar

or

return $anArrayVar

but having

return $anArray[a GalleryStatus object, $anyOtherTypeVar]

seemed a little confusing, but as I'm seeing it's possible with PHP (would it be possible with Java too?, well, that's for another discussion and forum :) )

I agree that using null would be faster but don't you think it wouldn't be too clear?, many programmers are used to true/1 for success and false/0 for error, but I guess you have already test and there are performance issues in favor of using null.

Regards!

Alexis Bellido - Ventanazul web solutions
 
valiant

Joined: 2003-01-04
Posts: 32509
Posted: Sun, 2006-01-01 05:03

php is a weak typed language that is it doesn't care too much about data types (integer vs. string vs. boolean, ...) thus you can easily make an array of different data types, e.g. return array(5, "hello", new GalleryStatus() );

java / C / ... are strong typed languages and you couldn't easily build an array of different data types. of course there are ways. and of course you can return such a collection in functions.
 
alexisb
alexisb's picture

Joined: 2005-11-24
Posts: 56
Posted: Sun, 2006-01-01 16:42

Hi Valiant, very interesting detail, this was getting me confused because I was trying to compare with Java, now everything has more sense.

Thanks a lot!

Alexis Bellido - Ventanazul web solutions
 
alexisb
alexisb's picture

Joined: 2005-11-24
Posts: 56
Posted: Mon, 2006-01-23 01:43
valiant wrote:
In G2.1, we'll change this pattern slightly and success will be replaced by null, to make it even faster.
instead of
return array(GalleryStatus::success(), array())
you'll write
return array(null, array())
and the calling function will check
if ($ret) {
instead of
if ($ret->isError()) {
and only in case of an error, you'll actually create / deal with GalleryStatus objects.

Hi Valiant, I am testing Gallery 2.1 and have already seen this change, however I think the above quote is a little confusing, shouldn't be "error will be replaced by null"?

I'm seeing code like:

list ($ret, $rootId) =
		GalleryCoreApi::getPluginParameter('module', 'core', 'id.rootAlbum');
	    if ($ret) {
		return $ret->wrap(__FILE__, __LINE__);
	    }

which makes me think error is null.

Please confirm.

Thanks!

Updated: Sorry, I got it, you are right, if success is null then something different would be an error, that's why saying if ($ret) it's like saying "if there is an error". Neat ;)