[java] Should a retrieval method return 'null' or throw an exception when it can't produce the return value?

I am using java language,I have a method that is supposed to return an object if it is found.

If it is not found, should I:

1. return null
2. throw an exception
3. other

Which is the best practise or idiom?

Generally it should return null. The code calling the method should decide whether to throw an exception or to attempt something else.

Exceptions are related to Design by Contract.

The interface of an objects is actually a contract between two objects, the caller must meet the contract or else the receiver may just fail with an exception. There are two possible contracts

1) all input the method is valid, in which case you must return null when the object is not found.

2) only some input is valid, ie that which results in a found object. In which case you MUST offer a second method that allows the caller to determine if its input will be correct. For example

is_present(key)
find(key) throws Exception

IF and ONLY IF you provide both methods of the 2nd contract, you are allowed to throw an exception is nothing is found!

Return a null, exceptions are exactly that: something your code does that isn't expected.

It depends on the nature of the method and how it will be used. If it is normal behavior that the object may not be found, then return null. If it is normal behavior that the object is always found, throw an exception.

As a rule of thumb, use exceptions only for when something exceptional occurs. Don't write the code in such a way that exception throwing and catching is part of its normal operation.

I just wanted to recapitulate the options mentioned before, throwing some new ones in:

1. return null
2. throw an Exception
3. use the null object pattern
4. provide a boolean parameter to you method, so the caller can chose if he wants you to throw an exception
5. provide an extra parameter, so the caller can set a value which he gets back if no value is found

Or you might combine these options:

Provide several overloaded versions of your getter, so the caller can decide which way to go. In most cases, only the first one has an implementation of the search algorithm, and the other ones just wrap around the first one:

Object findObjectOrNull(String key);
Object findObjectOrThrow(String key) throws SomeException;
Object findObjectOrCreate(String key, SomeClass dataNeededToCreateNewObject);
Object findObjectOrDefault(String key, Object defaultReturnValue);

Even if you choose to provide only one implementation, you might want to use a naming convention like that to clarify your contract, and it helps you should you ever decide to add other implementations as well.

You should not overuse it, but it may be helpfull, espeacially when writing a helper Class which you will use in hundreds of different applications with many different error handling conventions.

In some functions I add a parameter:

..., bool verify = true)

True means throw, false means return some error return value. This way, whoever uses this function has both options. The default should be true, for the benefit of those who forget about error handling.

Only throw an exception if it is truly an error. If it is expected behavior for the object to not exist, return the null.

Otherwise it is a matter of preference.

Or return an Option

An option is basically a container class that forces the client to handle booth cases. Scala has this concept, look up it's API.

Then you have methods like T getOrElse(T valueIfNull) on this object thet either return the found object, or an allternative the client specifieces.

Unfortunately JDK is inconsistent, if you trying access non existing key in resource bundle, you get not found exception and when you request value from map you get null if it doesn't exists. So I would change winner answer to the following, if found value can be null, then raise exception when it isn't found, otherwise return null. So follow to the rule with one exception, if you need to know why value isn't found then always raise exception, or..

Generally it should return null. The code calling the method should decide whether to throw an exception or to attempt something else.

Exceptions should be exceptional. Return null if it is valid to return a null.

Depends on what it means that the object is not found.

If it's a normal state of affairs, then return null. This is just something that might happen once in an while, and the callers should check for it.

If it's an error, then throw an exception, the callers should decide what to do with the error condition of missing object.

Ultimately either would work, although most people generally consider it good practice to only use Exceptions when something, well, Exceptional has happened.

As a general rule, if the method should always return an object, then go with the exception. If you anticipate the occasional null and want to handle it in a certain way, go with the null.

Whatever you do, I highly advise against the third option: Returning a string that says "WTF".

Don't think anyone mentioned the overhead in exception handling - takes additional resources to load up and process the exception so unless its a true app killing or process stopping event (going forward would cause more harm than good) I would opt for passing back a value the calling environment could interpret as it sees fit.

Return a null instead of throwing an exception and clearly document the possibility of a null return value in the API documentation. If the calling code doesn't honor the API and check for the null case, it will most probably result in some sort of "null pointer exception" anyway :)

In C++, I can think of 3 different flavors of setting up a method that finds an object.

Option A

Object *findObject(Key &key);

Return null when an object can't be found. Nice and simple. I'd go with this one. The alternative approaches below are for people who don't hate out-params.

Option B

void findObject(Key &key, Object &found);

Pass in a reference to variable that will be receiving the object. The method thrown an exception when an object can't be found. This convention is probably more suitable if it's not really expected for an object not to be found -- hence you throw an exception to signify that it's an unexpected case.

Option C

bool findObject(Key &key, Object &found);

The method returns false when an object can't be found. The advantage of this over option A is that you can check for the error case in one clear step:

if (!findObject(myKey, myObj)) { ...

The "other" option could be to let the find method take an additional parameter with a default object that would be returned if the sought for object cannot be found.

Otherwise I'd just return null unless it really is an exceptional case when the object isn't found.

If it's important for client code to know the difference between found and not found and this is supposed to be a routine behavior, then it's best to return null. Client code can then decide what to do.

Advantages of throwing an exception:

1. Cleaner control flow in your calling code. Checking for null injects a conditional branch which is natively handled by try/catch. Checking for null doesn't indicate what it is you're checking for - are you checking for null because you're looking for an error you're expecting, or are you checking for null so you don't pass it further on downchain?
2. Removes ambiguity of what "null" means. Is null representative of an error or is null what is actually stored in the value? Hard to say when you only have one thing to base that determination off of.
3. Improved consistency between method behavior in an application. Exceptions are typically exposed in method signatures, so you're more able to understand what edge cases the methods in an application account for, and what information your application can react to in a predictable manner.

For more explanation with examples, see: http://metatations.com/2011/11/17/returning-null-vs-throwing-an-exception/

It not containing the object can happen during normal operations and should be dealt with by the caller return NULL.

If not containing the object indicates a bug by the calling code or internal state then do an assert.

If not containing the object indicates an infrequent event. (Like someone deleted an item from the store while you were checking out the item at the same time.) Then throw an exception.

If it's important for client code to know the difference between found and not found and this is supposed to be a routine behavior, then it's best to return null. Client code can then decide what to do.

I just wanted to recapitulate the options mentioned before, throwing some new ones in:

1. return null
2. throw an Exception
3. use the null object pattern
4. provide a boolean parameter to you method, so the caller can chose if he wants you to throw an exception
5. provide an extra parameter, so the caller can set a value which he gets back if no value is found

Or you might combine these options:

Provide several overloaded versions of your getter, so the caller can decide which way to go. In most cases, only the first one has an implementation of the search algorithm, and the other ones just wrap around the first one:

Object findObjectOrNull(String key);
Object findObjectOrThrow(String key) throws SomeException;
Object findObjectOrCreate(String key, SomeClass dataNeededToCreateNewObject);
Object findObjectOrDefault(String key, Object defaultReturnValue);

Even if you choose to provide only one implementation, you might want to use a naming convention like that to clarify your contract, and it helps you should you ever decide to add other implementations as well.

You should not overuse it, but it may be helpfull, espeacially when writing a helper Class which you will use in hundreds of different applications with many different error handling conventions.

It not containing the object can happen during normal operations and should be dealt with by the caller return NULL.

If not containing the object indicates a bug by the calling code or internal state then do an assert.

If not containing the object indicates an infrequent event. (Like someone deleted an item from the store while you were checking out the item at the same time.) Then throw an exception.

In some functions I add a parameter:

..., bool verify = true)

True means throw, false means return some error return value. This way, whoever uses this function has both options. The default should be true, for the benefit of those who forget about error handling.

Use the null object pattern or throw an exception.

it depends if your language and code promotes: LBYL (look before you leap) or EAFP (easier to ask forgiveness than permission)

LBYL says you should check for values (so return a null)
EAFP says to just try the operation and see if it fails (throw an exception)

though I agree with above.. exceptions should be used for exceptional/error conditions, and returning a null is best when using checks.

EAFP vs. LBYL in Python:
http://mail.python.org/pipermail/python-list/2003-May/205182.html (Web Archive)

Return a null instead of throwing an exception and clearly document the possibility of a null return value in the API documentation. If the calling code doesn't honor the API and check for the null case, it will most probably result in some sort of "null pointer exception" anyway :)

In C++, I can think of 3 different flavors of setting up a method that finds an object.

Option A

Object *findObject(Key &key);

Return null when an object can't be found. Nice and simple. I'd go with this one. The alternative approaches below are for people who don't hate out-params.

Option B

void findObject(Key &key, Object &found);

Pass in a reference to variable that will be receiving the object. The method thrown an exception when an object can't be found. This convention is probably more suitable if it's not really expected for an object not to be found -- hence you throw an exception to signify that it's an unexpected case.

Option C

bool findObject(Key &key, Object &found);

The method returns false when an object can't be found. The advantage of this over option A is that you can check for the error case in one clear step:

if (!findObject(myKey, myObj)) { ...

Use the null object pattern or throw an exception.

As a general rule, if the method should always return an object, then go with the exception. If you anticipate the occasional null and want to handle it in a certain way, go with the null.

Whatever you do, I highly advise against the third option: Returning a string that says "WTF".

Just ask yourself: "is it an exceptional case that the object is not found"? If it is expected to happen in the normal course of your program, you probably should not raise an exception (since it is not exceptional behavior).

Short version: use exceptions to handle exceptional behavior, not to handle normal flow of control in your program.

-Alan.

In data layer code, I some times use the following code, allowing the caller to decide if "object not found" means an error has occured.

DataType GetObject(DBConnection conn, string id, bool throwOnNotFound) {
    DataType retval = ... // find object in database
    if (retval != null || ! throwOnNotFound) {
        return retval;
    } else {
        throw new NoRowsFoundException("DataType object with id {id} not found in database");
    }
}

DataType GetObject(DBConnection conn, string id) {
    return GetObject(conn, id, true);
} 

Don't think anyone mentioned the overhead in exception handling - takes additional resources to load up and process the exception so unless its a true app killing or process stopping event (going forward would cause more harm than good) I would opt for passing back a value the calling environment could interpret as it sees fit.

Exceptions should be exceptional. Return null if it is valid to return a null.

Exceptions are related to Design by Contract.

The interface of an objects is actually a contract between two objects, the caller must meet the contract or else the receiver may just fail with an exception. There are two possible contracts

1) all input the method is valid, in which case you must return null when the object is not found.

2) only some input is valid, ie that which results in a found object. In which case you MUST offer a second method that allows the caller to determine if its input will be correct. For example

is_present(key)
find(key) throws Exception

IF and ONLY IF you provide both methods of the 2nd contract, you are allowed to throw an exception is nothing is found!

Return a null, exceptions are exactly that: something your code does that isn't expected.

As long as it's supposed to return a reference to the object, returning a NULL should be good.

However, if it's returning the whole bloody thing (like in C++ if you do: 'return blah;' rather than 'return &blah;' (or 'blah' is a pointer), then you can't return a NULL, because it's not of type 'object'. In that case, throwing an exception, or returning a blank object that doesn't have a success flag set is how I would approach the problem.

That really depends on if you expect to find the object, or not. If you follow the school of thought that exceptions should be used for indicating something, well, err, exceptional has occured then:

• Object found; return object
• Object not-found; throw exception

Otherwise, return null.

I agree with what seems to be the consensus here (return null if "not found" is a normal possible outcome, or throw an exception if the semantics of the situation require that the object always be found).

There is, however, a third possibility that might make sense depending on your particular situation. Your method could return a default object of some sort in the "not found" condition, allowing calling code to be assured that it will always receive a valid object without the need for null checking or exception catching.

Only throw an exception if it is truly an error. If it is expected behavior for the object to not exist, return the null.

Otherwise it is a matter of preference.

That depends on your method. If you method is supposed to always return a valid object and none is found, throwing an exception is the way to go. If the method is just ment to return an object which might or might not be there (like perhaps a image on a contact person) you shouldn't raise an error.

You might also want to expose a method returning a boolean true/false if this method actually will return an object so you don't have to either a) check for null or b) catch an exception

Or return an Option

An option is basically a container class that forces the client to handle booth cases. Scala has this concept, look up it's API.

Then you have methods like T getOrElse(T valueIfNull) on this object thet either return the found object, or an allternative the client specifieces.

Use the null object pattern or throw an exception.

The "other" option could be to let the find method take an additional parameter with a default object that would be returned if the sought for object cannot be found.

Otherwise I'd just return null unless it really is an exceptional case when the object isn't found.

Advantages of throwing an exception:

1. Cleaner control flow in your calling code. Checking for null injects a conditional branch which is natively handled by try/catch. Checking for null doesn't indicate what it is you're checking for - are you checking for null because you're looking for an error you're expecting, or are you checking for null so you don't pass it further on downchain?
2. Removes ambiguity of what "null" means. Is null representative of an error or is null what is actually stored in the value? Hard to say when you only have one thing to base that determination off of.
3. Improved consistency between method behavior in an application. Exceptions are typically exposed in method signatures, so you're more able to understand what edge cases the methods in an application account for, and what information your application can react to in a predictable manner.

For more explanation with examples, see: http://metatations.com/2011/11/17/returning-null-vs-throwing-an-exception/

Prefer returning null --

If the caller uses it without checking, the exception happens right there anyway.

If the caller doesn't really use it, don't tax him a try/catch block

I prefer to just return a null, and rely on the caller to handle it appropriately. The (for lack of a better word) exception is if I am absolutely 'certain' this method will return an object. In that case a failure is an exceptional should and should throw.

If null never indicates an error then just return null.

If null is always an error then throw an exception.

If null is sometimes an exception then code two routines. One routine throws an exception and the other is a boolean test routine that returns the object in an output parameter and the routine returns a false if the object was not found.

It's hard to misuse a Try routine. It's real easy to forget to check for null.

So when null is an error you just write

object o = FindObject();

When the null isn't an error you can code something like

if (TryFindObject(out object o)
  // Do something with o
else
  // o was not found

Just ask yourself: "is it an exceptional case that the object is not found"? If it is expected to happen in the normal course of your program, you probably should not raise an exception (since it is not exceptional behavior).

Short version: use exceptions to handle exceptional behavior, not to handle normal flow of control in your program.

-Alan.

As long as it's supposed to return a reference to the object, returning a NULL should be good.

However, if it's returning the whole bloody thing (like in C++ if you do: 'return blah;' rather than 'return &blah;' (or 'blah' is a pointer), then you can't return a NULL, because it's not of type 'object'. In that case, throwing an exception, or returning a blank object that doesn't have a success flag set is how I would approach the problem.

If null never indicates an error then just return null.

If null is always an error then throw an exception.

If null is sometimes an exception then code two routines. One routine throws an exception and the other is a boolean test routine that returns the object in an output parameter and the routine returns a false if the object was not found.

It's hard to misuse a Try routine. It's real easy to forget to check for null.

So when null is an error you just write

object o = FindObject();

When the null isn't an error you can code something like

if (TryFindObject(out object o)
  // Do something with o
else
  // o was not found

That depends on your method. If you method is supposed to always return a valid object and none is found, throwing an exception is the way to go. If the method is just ment to return an object which might or might not be there (like perhaps a image on a contact person) you shouldn't raise an error.

You might also want to expose a method returning a boolean true/false if this method actually will return an object so you don't have to either a) check for null or b) catch an exception

Just ask yourself: "is it an exceptional case that the object is not found"? If it is expected to happen in the normal course of your program, you probably should not raise an exception (since it is not exceptional behavior).

Short version: use exceptions to handle exceptional behavior, not to handle normal flow of control in your program.

-Alan.

Return a null instead of throwing an exception and clearly document the possibility of a null return value in the API documentation. If the calling code doesn't honor the API and check for the null case, it will most probably result in some sort of "null pointer exception" anyway :)

In C++, I can think of 3 different flavors of setting up a method that finds an object.

Option A

Object *findObject(Key &key);

Return null when an object can't be found. Nice and simple. I'd go with this one. The alternative approaches below are for people who don't hate out-params.

Option B

void findObject(Key &key, Object &found);

Pass in a reference to variable that will be receiving the object. The method thrown an exception when an object can't be found. This convention is probably more suitable if it's not really expected for an object not to be found -- hence you throw an exception to signify that it's an unexpected case.

Option C

bool findObject(Key &key, Object &found);

The method returns false when an object can't be found. The advantage of this over option A is that you can check for the error case in one clear step:

if (!findObject(myKey, myObj)) { ...

Depends on what it means that the object is not found.

If it's a normal state of affairs, then return null. This is just something that might happen once in an while, and the callers should check for it.

If it's an error, then throw an exception, the callers should decide what to do with the error condition of missing object.

Ultimately either would work, although most people generally consider it good practice to only use Exceptions when something, well, Exceptional has happened.

If not finding it is an exceptional event (i.e. it should be there under normal circumstances), then throw. Otherwise, return a "not found" value (can be null, but does not have to), or even have the method return a boolean for found/notfound and an out parameter for the actual object.

Return a null, exceptions are exactly that: something your code does that isn't expected.

Exceptions are related to Design by Contract.

The interface of an objects is actually a contract between two objects, the caller must meet the contract or else the receiver may just fail with an exception. There are two possible contracts

1) all input the method is valid, in which case you must return null when the object is not found.

2) only some input is valid, ie that which results in a found object. In which case you MUST offer a second method that allows the caller to determine if its input will be correct. For example

is_present(key)
find(key) throws Exception

IF and ONLY IF you provide both methods of the 2nd contract, you are allowed to throw an exception is nothing is found!

If null never indicates an error then just return null.

If null is always an error then throw an exception.

If null is sometimes an exception then code two routines. One routine throws an exception and the other is a boolean test routine that returns the object in an output parameter and the routine returns a false if the object was not found.

It's hard to misuse a Try routine. It's real easy to forget to check for null.

So when null is an error you just write

object o = FindObject();

When the null isn't an error you can code something like

if (TryFindObject(out object o)
  // Do something with o
else
  // o was not found

Be consistent with the API(s) you're using.

In some functions I add a parameter:

..., bool verify = true)

True means throw, false means return some error return value. This way, whoever uses this function has both options. The default should be true, for the benefit of those who forget about error handling.

If not finding it is an exceptional event (i.e. it should be there under normal circumstances), then throw. Otherwise, return a "not found" value (can be null, but does not have to), or even have the method return a boolean for found/notfound and an out parameter for the actual object.

As a general rule, if the method should always return an object, then go with the exception. If you anticipate the occasional null and want to handle it in a certain way, go with the null.

Whatever you do, I highly advise against the third option: Returning a string that says "WTF".

Depends on what it means that the object is not found.

If it's a normal state of affairs, then return null. This is just something that might happen once in an while, and the callers should check for it.

If it's an error, then throw an exception, the callers should decide what to do with the error condition of missing object.

Ultimately either would work, although most people generally consider it good practice to only use Exceptions when something, well, Exceptional has happened.

The "other" option could be to let the find method take an additional parameter with a default object that would be returned if the sought for object cannot be found.

Otherwise I'd just return null unless it really is an exceptional case when the object isn't found.

Generally it should return null. The code calling the method should decide whether to throw an exception or to attempt something else.

Be consistent with the API(s) you're using.

In some functions I add a parameter:

..., bool verify = true)

True means throw, false means return some error return value. This way, whoever uses this function has both options. The default should be true, for the benefit of those who forget about error handling.

Unfortunately JDK is inconsistent, if you trying access non existing key in resource bundle, you get not found exception and when you request value from map you get null if it doesn't exists. So I would change winner answer to the following, if found value can be null, then raise exception when it isn't found, otherwise return null. So follow to the rule with one exception, if you need to know why value isn't found then always raise exception, or..

Be consistent with the API(s) you're using.

In data layer code, I some times use the following code, allowing the caller to decide if "object not found" means an error has occured.

DataType GetObject(DBConnection conn, string id, bool throwOnNotFound) {
    DataType retval = ... // find object in database
    if (retval != null || ! throwOnNotFound) {
        return retval;
    } else {
        throw new NoRowsFoundException("DataType object with id {id} not found in database");
    }
}

DataType GetObject(DBConnection conn, string id) {
    return GetObject(conn, id, true);
} 

referring only to the case where null is not considered an exceptional behavior i am definitely for the try method, it is clear, no need to "read the book" or "look before you leap" as was said here

so basically:

bool TryFindObject(RequestParam request, out ResponseParam response)

and this means that the user's code will also be clear

...
if(TryFindObject(request, out response)
{
  handleSuccess(response)
}
else
{
  handleFailure()
}
...

Exceptions should be exceptional. Return null if it is valid to return a null.

Just ask yourself: "is it an exceptional case that the object is not found"? If it is expected to happen in the normal course of your program, you probably should not raise an exception (since it is not exceptional behavior).

Short version: use exceptions to handle exceptional behavior, not to handle normal flow of control in your program.

-Alan.

I just wanted to recapitulate the options mentioned before, throwing some new ones in:

1. return null
2. throw an Exception
3. use the null object pattern
4. provide a boolean parameter to you method, so the caller can chose if he wants you to throw an exception
5. provide an extra parameter, so the caller can set a value which he gets back if no value is found

Or you might combine these options:

Provide several overloaded versions of your getter, so the caller can decide which way to go. In most cases, only the first one has an implementation of the search algorithm, and the other ones just wrap around the first one:

Object findObjectOrNull(String key);
Object findObjectOrThrow(String key) throws SomeException;
Object findObjectOrCreate(String key, SomeClass dataNeededToCreateNewObject);
Object findObjectOrDefault(String key, Object defaultReturnValue);

Even if you choose to provide only one implementation, you might want to use a naming convention like that to clarify your contract, and it helps you should you ever decide to add other implementations as well.

You should not overuse it, but it may be helpfull, espeacially when writing a helper Class which you will use in hundreds of different applications with many different error handling conventions.

Only throw an exception if it is truly an error. If it is expected behavior for the object to not exist, return the null.

Otherwise it is a matter of preference.

Return a null instead of throwing an exception and clearly document the possibility of a null return value in the API documentation. If the calling code doesn't honor the API and check for the null case, it will most probably result in some sort of "null pointer exception" anyway :)

In C++, I can think of 3 different flavors of setting up a method that finds an object.

Option A

Object *findObject(Key &key);

Return null when an object can't be found. Nice and simple. I'd go with this one. The alternative approaches below are for people who don't hate out-params.

Option B

void findObject(Key &key, Object &found);

Pass in a reference to variable that will be receiving the object. The method thrown an exception when an object can't be found. This convention is probably more suitable if it's not really expected for an object not to be found -- hence you throw an exception to signify that it's an unexpected case.

Option C

bool findObject(Key &key, Object &found);

The method returns false when an object can't be found. The advantage of this over option A is that you can check for the error case in one clear step:

if (!findObject(myKey, myObj)) { ...

If you are using a library or another class which throws an exception, you should rethrow it. Here is an example. Example2.java is like library and Example.java uses it's object. Main.java is an example to handle this Exception. You should show a meaningful message and (if needed) stack trace to the user in the calling side.

Main.java

public class Main {
public static void main(String[] args) {
    Example example = new Example();

    try {
        Example2 obj = example.doExample();

        if(obj == null){
            System.out.println("Hey object is null!");
        }
    } catch (Exception e) {
        System.out.println("Congratulations, you caught the exception!");
        System.out.println("Here is stack trace:");
        e.printStackTrace();
    }
}
}

Example.java

/**
 * Example.java
 * @author Seval
 * @date 10/22/2014
 */
public class Example {
    /**
     * Returns Example2 object
     * If there is no Example2 object, throws exception
     * 
     * @return obj Example2
     * @throws Exception
     */
    public Example2 doExample() throws Exception {
        try {
            // Get the object
            Example2 obj = new Example2();

            return obj;

        } catch (Exception e) {
            // Log the exception and rethrow
            // Log.logException(e);
            throw e;
        }

    }
}

Example2.java

 /**
 * Example2.java
 * @author Seval
 *
 */
public class Example2 {
    /**
     * Constructor of Example2
     * @throws Exception
     */
    public Example2() throws Exception{
        throw new Exception("Please set the \"obj\"");
    }

}

It depends on the nature of the method and how it will be used. If it is normal behavior that the object may not be found, then return null. If it is normal behavior that the object is always found, throw an exception.

As a rule of thumb, use exceptions only for when something exceptional occurs. Don't write the code in such a way that exception throwing and catching is part of its normal operation.

As a general rule, if the method should always return an object, then go with the exception. If you anticipate the occasional null and want to handle it in a certain way, go with the null.

Whatever you do, I highly advise against the third option: Returning a string that says "WTF".

If it's important for client code to know the difference between found and not found and this is supposed to be a routine behavior, then it's best to return null. Client code can then decide what to do.

I just wanted to recapitulate the options mentioned before, throwing some new ones in:

1. return null
2. throw an Exception
3. use the null object pattern
4. provide a boolean parameter to you method, so the caller can chose if he wants you to throw an exception
5. provide an extra parameter, so the caller can set a value which he gets back if no value is found

Or you might combine these options:

Provide several overloaded versions of your getter, so the caller can decide which way to go. In most cases, only the first one has an implementation of the search algorithm, and the other ones just wrap around the first one:

Object findObjectOrNull(String key);
Object findObjectOrThrow(String key) throws SomeException;
Object findObjectOrCreate(String key, SomeClass dataNeededToCreateNewObject);
Object findObjectOrDefault(String key, Object defaultReturnValue);

Even if you choose to provide only one implementation, you might want to use a naming convention like that to clarify your contract, and it helps you should you ever decide to add other implementations as well.

You should not overuse it, but it may be helpfull, espeacially when writing a helper Class which you will use in hundreds of different applications with many different error handling conventions.

If the method returns a collection, then return an empty collection (like sayed above). But please not Collections.EMPTY_LIST or such! (in case of Java)

If the method retrives a single object, then You have some options.

1. If the method should always find the result and it's a real exception case not to find the object, then you should throw an exception (in Java: please an unchecked Exception)
2. (Java only) If you can tolerate that the method throws a checked exception, throw a project specific ObjectNotFoundException or the like. In this case the compiler says you if you forget to handle the exception. (This is my preferred handling of not found things in Java.)
3. If you say it's really ok, if the object is not found and your Method name is like findBookForAuthorOrReturnNull(..), then you can return null. In this case it is strongly recomminded to use some sort of static check or compiler check, wich prevents dereferencing of the result without a null check. In case of Java it can be eg. FindBugs (see DefaultAnnotation at http://findbugs.sourceforge.net/manual/annotations.html) or IntelliJ-Checking.

Be careful, if you decide to return a null. If you are not the only programmer in project you will get NullPointerExceptions (in Java or whatever in other Languages) at run time! So don't return nulls which are not checked at compile time.

That really depends on if you expect to find the object, or not. If you follow the school of thought that exceptions should be used for indicating something, well, err, exceptional has occured then:

• Object found; return object
• Object not-found; throw exception

Otherwise, return null.

Here are a couple more suggestions.

If returning a collection, avoid returning null, return an empty collection which makes enumeration easier to deal with without a null check first.

Several .NET API's use the pattern of a thrownOnError parameter which gives the caller the choice as whether it is really an exceptional situation or not if the object is not found. Type.GetType is an example of this. Another common pattern with BCL is the TryGet pattern where a boolean is returned and the value is passed via an output parameter.

You could also consider the Null Object pattern in some circumstances which can either be a default or a version with no behaviour. The key is avoid null checks throughout the code base. See here for more information http://geekswithblogs.net/dsellers/archive/2006/09/08/90656.aspx

it depends if your language and code promotes: LBYL (look before you leap) or EAFP (easier to ask forgiveness than permission)

LBYL says you should check for values (so return a null)
EAFP says to just try the operation and see if it fails (throw an exception)

though I agree with above.. exceptions should be used for exceptional/error conditions, and returning a null is best when using checks.

EAFP vs. LBYL in Python:
http://mail.python.org/pipermail/python-list/2003-May/205182.html (Web Archive)

That depends on your method. If you method is supposed to always return a valid object and none is found, throwing an exception is the way to go. If the method is just ment to return an object which might or might not be there (like perhaps a image on a contact person) you shouldn't raise an error.

You might also want to expose a method returning a boolean true/false if this method actually will return an object so you don't have to either a) check for null or b) catch an exception

The "other" option could be to let the find method take an additional parameter with a default object that would be returned if the sought for object cannot be found.

Otherwise I'd just return null unless it really is an exceptional case when the object isn't found.

Or return an Option

An option is basically a container class that forces the client to handle booth cases. Scala has this concept, look up it's API.

Then you have methods like T getOrElse(T valueIfNull) on this object thet either return the found object, or an allternative the client specifieces.

That depends on your method. If you method is supposed to always return a valid object and none is found, throwing an exception is the way to go. If the method is just ment to return an object which might or might not be there (like perhaps a image on a contact person) you shouldn't raise an error.

You might also want to expose a method returning a boolean true/false if this method actually will return an object so you don't have to either a) check for null or b) catch an exception

In data layer code, I some times use the following code, allowing the caller to decide if "object not found" means an error has occured.

DataType GetObject(DBConnection conn, string id, bool throwOnNotFound) {
    DataType retval = ... // find object in database
    if (retval != null || ! throwOnNotFound) {
        return retval;
    } else {
        throw new NoRowsFoundException("DataType object with id {id} not found in database");
    }
}

DataType GetObject(DBConnection conn, string id) {
    return GetObject(conn, id, true);
} 

Return a null, exceptions are exactly that: something your code does that isn't expected.

It not containing the object can happen during normal operations and should be dealt with by the caller return NULL.

If not containing the object indicates a bug by the calling code or internal state then do an assert.

If not containing the object indicates an infrequent event. (Like someone deleted an item from the store while you were checking out the item at the same time.) Then throw an exception.

I agree with what seems to be the consensus here (return null if "not found" is a normal possible outcome, or throw an exception if the semantics of the situation require that the object always be found).

There is, however, a third possibility that might make sense depending on your particular situation. Your method could return a default object of some sort in the "not found" condition, allowing calling code to be assured that it will always receive a valid object without the need for null checking or exception catching.

Only throw an exception if it is truly an error. If it is expected behavior for the object to not exist, return the null.

Otherwise it is a matter of preference.

If not finding it is an exceptional event (i.e. it should be there under normal circumstances), then throw. Otherwise, return a "not found" value (can be null, but does not have to), or even have the method return a boolean for found/notfound and an out parameter for the actual object.

I agree with what seems to be the consensus here (return null if "not found" is a normal possible outcome, or throw an exception if the semantics of the situation require that the object always be found).

There is, however, a third possibility that might make sense depending on your particular situation. Your method could return a default object of some sort in the "not found" condition, allowing calling code to be assured that it will always receive a valid object without the need for null checking or exception catching.

Exceptions are related to Design by Contract.

The interface of an objects is actually a contract between two objects, the caller must meet the contract or else the receiver may just fail with an exception. There are two possible contracts

1) all input the method is valid, in which case you must return null when the object is not found.

2) only some input is valid, ie that which results in a found object. In which case you MUST offer a second method that allows the caller to determine if its input will be correct. For example

is_present(key)
find(key) throws Exception

IF and ONLY IF you provide both methods of the 2nd contract, you are allowed to throw an exception is nothing is found!

I prefer to just return a null, and rely on the caller to handle it appropriately. The (for lack of a better word) exception is if I am absolutely 'certain' this method will return an object. In that case a failure is an exceptional should and should throw.

Here are a couple more suggestions.

If returning a collection, avoid returning null, return an empty collection which makes enumeration easier to deal with without a null check first.

Several .NET API's use the pattern of a thrownOnError parameter which gives the caller the choice as whether it is really an exceptional situation or not if the object is not found. Type.GetType is an example of this. Another common pattern with BCL is the TryGet pattern where a boolean is returned and the value is passed via an output parameter.

You could also consider the Null Object pattern in some circumstances which can either be a default or a version with no behaviour. The key is avoid null checks throughout the code base. See here for more information http://geekswithblogs.net/dsellers/archive/2006/09/08/90656.aspx

it depends if your language and code promotes: LBYL (look before you leap) or EAFP (easier to ask forgiveness than permission)

LBYL says you should check for values (so return a null)
EAFP says to just try the operation and see if it fails (throw an exception)

though I agree with above.. exceptions should be used for exceptional/error conditions, and returning a null is best when using checks.

EAFP vs. LBYL in Python:
http://mail.python.org/pipermail/python-list/2003-May/205182.html (Web Archive)

If the method returns a collection, then return an empty collection (like sayed above). But please not Collections.EMPTY_LIST or such! (in case of Java)

If the method retrives a single object, then You have some options.

1. If the method should always find the result and it's a real exception case not to find the object, then you should throw an exception (in Java: please an unchecked Exception)
2. (Java only) If you can tolerate that the method throws a checked exception, throw a project specific ObjectNotFoundException or the like. In this case the compiler says you if you forget to handle the exception. (This is my preferred handling of not found things in Java.)
3. If you say it's really ok, if the object is not found and your Method name is like findBookForAuthorOrReturnNull(..), then you can return null. In this case it is strongly recomminded to use some sort of static check or compiler check, wich prevents dereferencing of the result without a null check. In case of Java it can be eg. FindBugs (see DefaultAnnotation at http://findbugs.sourceforge.net/manual/annotations.html) or IntelliJ-Checking.

Be careful, if you decide to return a null. If you are not the only programmer in project you will get NullPointerExceptions (in Java or whatever in other Languages) at run time! So don't return nulls which are not checked at compile time.

Generally it should return null. The code calling the method should decide whether to throw an exception or to attempt something else.

referring only to the case where null is not considered an exceptional behavior i am definitely for the try method, it is clear, no need to "read the book" or "look before you leap" as was said here

so basically:

bool TryFindObject(RequestParam request, out ResponseParam response)

and this means that the user's code will also be clear

...
if(TryFindObject(request, out response)
{
  handleSuccess(response)
}
else
{
  handleFailure()
}
...

Exceptions should be exceptional. Return null if it is valid to return a null.

Here are a couple more suggestions.

If returning a collection, avoid returning null, return an empty collection which makes enumeration easier to deal with without a null check first.

Several .NET API's use the pattern of a thrownOnError parameter which gives the caller the choice as whether it is really an exceptional situation or not if the object is not found. Type.GetType is an example of this. Another common pattern with BCL is the TryGet pattern where a boolean is returned and the value is passed via an output parameter.

You could also consider the Null Object pattern in some circumstances which can either be a default or a version with no behaviour. The key is avoid null checks throughout the code base. See here for more information http://geekswithblogs.net/dsellers/archive/2006/09/08/90656.aspx

That really depends on if you expect to find the object, or not. If you follow the school of thought that exceptions should be used for indicating something, well, err, exceptional has occured then:

• Object found; return object
• Object not-found; throw exception

Otherwise, return null.

Depends on what it means that the object is not found.

If it's a normal state of affairs, then return null. This is just something that might happen once in an while, and the callers should check for it.

If it's an error, then throw an exception, the callers should decide what to do with the error condition of missing object.

Ultimately either would work, although most people generally consider it good practice to only use Exceptions when something, well, Exceptional has happened.

It depends on the nature of the method and how it will be used. If it is normal behavior that the object may not be found, then return null. If it is normal behavior that the object is always found, throw an exception.

As a rule of thumb, use exceptions only for when something exceptional occurs. Don't write the code in such a way that exception throwing and catching is part of its normal operation.

I prefer to just return a null, and rely on the caller to handle it appropriately. The (for lack of a better word) exception is if I am absolutely 'certain' this method will return an object. In that case a failure is an exceptional should and should throw.

If not finding it is an exceptional event (i.e. it should be there under normal circumstances), then throw. Otherwise, return a "not found" value (can be null, but does not have to), or even have the method return a boolean for found/notfound and an out parameter for the actual object.

As long as it's supposed to return a reference to the object, returning a NULL should be good.

However, if it's returning the whole bloody thing (like in C++ if you do: 'return blah;' rather than 'return &blah;' (or 'blah' is a pointer), then you can't return a NULL, because it's not of type 'object'. In that case, throwing an exception, or returning a blank object that doesn't have a success flag set is how I would approach the problem.

If null never indicates an error then just return null.

If null is always an error then throw an exception.

If null is sometimes an exception then code two routines. One routine throws an exception and the other is a boolean test routine that returns the object in an output parameter and the routine returns a false if the object was not found.

It's hard to misuse a Try routine. It's real easy to forget to check for null.

So when null is an error you just write

object o = FindObject();

When the null isn't an error you can code something like

if (TryFindObject(out object o)
  // Do something with o
else
  // o was not found

Prefer returning null --

If the caller uses it without checking, the exception happens right there anyway.

If the caller doesn't really use it, don't tax him a try/catch block

Don't think anyone mentioned the overhead in exception handling - takes additional resources to load up and process the exception so unless its a true app killing or process stopping event (going forward would cause more harm than good) I would opt for passing back a value the calling environment could interpret as it sees fit.

In data layer code, I some times use the following code, allowing the caller to decide if "object not found" means an error has occured.

DataType GetObject(DBConnection conn, string id, bool throwOnNotFound) {
    DataType retval = ... // find object in database
    if (retval != null || ! throwOnNotFound) {
        return retval;
    } else {
        throw new NoRowsFoundException("DataType object with id {id} not found in database");
    }
}

DataType GetObject(DBConnection conn, string id) {
    return GetObject(conn, id, true);
} 

It depends on the nature of the method and how it will be used. If it is normal behavior that the object may not be found, then return null. If it is normal behavior that the object is always found, throw an exception.

As a rule of thumb, use exceptions only for when something exceptional occurs. Don't write the code in such a way that exception throwing and catching is part of its normal operation.

Or return an Option

An option is basically a container class that forces the client to handle booth cases. Scala has this concept, look up it's API.

Then you have methods like T getOrElse(T valueIfNull) on this object thet either return the found object, or an allternative the client specifieces.

it depends if your language and code promotes: LBYL (look before you leap) or EAFP (easier to ask forgiveness than permission)

LBYL says you should check for values (so return a null)
EAFP says to just try the operation and see if it fails (throw an exception)

though I agree with above.. exceptions should be used for exceptional/error conditions, and returning a null is best when using checks.

EAFP vs. LBYL in Python:
http://mail.python.org/pipermail/python-list/2003-May/205182.html (Web Archive)

Don't think anyone mentioned the overhead in exception handling - takes additional resources to load up and process the exception so unless its a true app killing or process stopping event (going forward would cause more harm than good) I would opt for passing back a value the calling environment could interpret as it sees fit.

If it's important for client code to know the difference between found and not found and this is supposed to be a routine behavior, then it's best to return null. Client code can then decide what to do.

As long as it's supposed to return a reference to the object, returning a NULL should be good.

However, if it's returning the whole bloody thing (like in C++ if you do: 'return blah;' rather than 'return &blah;' (or 'blah' is a pointer), then you can't return a NULL, because it's not of type 'object'. In that case, throwing an exception, or returning a blank object that doesn't have a success flag set is how I would approach the problem.

It not containing the object can happen during normal operations and should be dealt with by the caller return NULL.

If not containing the object indicates a bug by the calling code or internal state then do an assert.

If not containing the object indicates an infrequent event. (Like someone deleted an item from the store while you were checking out the item at the same time.) Then throw an exception.

That really depends on if you expect to find the object, or not. If you follow the school of thought that exceptions should be used for indicating something, well, err, exceptional has occured then:

• Object found; return object
• Object not-found; throw exception

Otherwise, return null.

I agree with what seems to be the consensus here (return null if "not found" is a normal possible outcome, or throw an exception if the semantics of the situation require that the object always be found).

There is, however, a third possibility that might make sense depending on your particular situation. Your method could return a default object of some sort in the "not found" condition, allowing calling code to be assured that it will always receive a valid object without the need for null checking or exception catching.

If you are using a library or another class which throws an exception, you should rethrow it. Here is an example. Example2.java is like library and Example.java uses it's object. Main.java is an example to handle this Exception. You should show a meaningful message and (if needed) stack trace to the user in the calling side.

Main.java

public class Main {
public static void main(String[] args) {
    Example example = new Example();

    try {
        Example2 obj = example.doExample();

        if(obj == null){
            System.out.println("Hey object is null!");
        }
    } catch (Exception e) {
        System.out.println("Congratulations, you caught the exception!");
        System.out.println("Here is stack trace:");
        e.printStackTrace();
    }
}
}

Example.java

/**
 * Example.java
 * @author Seval
 * @date 10/22/2014
 */
public class Example {
    /**
     * Returns Example2 object
     * If there is no Example2 object, throws exception
     * 
     * @return obj Example2
     * @throws Exception
     */
    public Example2 doExample() throws Exception {
        try {
            // Get the object
            Example2 obj = new Example2();

            return obj;

        } catch (Exception e) {
            // Log the exception and rethrow
            // Log.logException(e);
            throw e;
        }

    }
}

Example2.java

 /**
 * Example2.java
 * @author Seval
 *
 */
public class Example2 {
    /**
     * Constructor of Example2
     * @throws Exception
     */
    public Example2() throws Exception{
        throw new Exception("Please set the \"obj\"");
    }

}

Be consistent with the API(s) you're using.

Use the null object pattern or throw an exception.

I prefer to just return a null, and rely on the caller to handle it appropriately. The (for lack of a better word) exception is if I am absolutely 'certain' this method will return an object. In that case a failure is an exceptional should and should throw.