This week's book giveaway is in the Kotlin forum.
We're giving away four copies of Kotlin in Action and have Dmitry Jemerov & Svetlana Isakova on-line!
See this thread for details.
Win a copy of Kotlin in Action this week in the Kotlin forum!
  • Post Reply Bookmark Topic Watch Topic
  • New Topic

API implementation decision  RSS feed

 
Jim Lang
Greenhorn
Posts: 27
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi all,
I couldn't decide where to post this so I posted it here...
I am looking at implementing an API in java, for java clients to connect to remote services, and there is a fundamental design decision that I am trying to resolve.
The question is whether it is better to implement the various different parts of the api with Exceptions to indicate particular errors, or to use a return type of 'Object' so that either an Integer containing an error code can be returned in the case of an error, or another specified collection/object in the case of success.
In the case of the former a client would be using a 'try/catch/finally' construct to deal with problems while for the latter problems would be dealt with in an 'if instanceof Integer... else...' kind of construct.
Can anyone advise me in this?
 
Robert Paris
Ranch Hand
Posts: 585
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
The best way to do it is:
- if something occurs during execution of a method/algorithm that indicates something is WRONG, then raise an exception
Exceptions are great, because instead of forcing people to:
1. Know that 1 means ok, 32 means bad, or null means an error occurred
2. put in numerous if...else statements
3. have to do additionally parsing of return
they can just say, "If it returns, i got something useful, if it raises an exception instead, clean up with..."
It makes for a much better flow of execution, and there is one other benefit. If your methods declare the exceptions they throw, you enforce better handling/flow on the developer. For example:
public String getName() throws ContactException;
1. This tells the developer, if something goes wrong it will be told to you in EXACTLY this manner, (i.e. the interface of ContactException)
2. They (the developer) can do nothing with this exception if they choose, but they must catch it so that the method can fail cleanly.
Hope this helps. If anyone else has better ideas or can explain this better please add your 2 cents!
 
Tim Holloway
Bartender
Posts: 18713
71
Android Eclipse IDE Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Since the dawn of programming, it's been common for functions to return bipolar objects.
Consider the common table search function: Search table T for value V. If found, return the index of V in T, else return -1.
In a very strongly-typed language, this is a BAD THING. The "good" return value is a member of the set of cardinal or ordinal numbers (that is, it's a positive integer). The "fail" return value is a member of the set of Whole Numbers (postive, zero, and negative integers). This opens up a large gray area for values -2, -3, -4, ... etc.
The basic design of most computer hardware at the low level and, since few care about that anymore, the amount of coding at the higher level make us accepting of that solution as one that is both machine- and people-efficient at the cost of bing somewhat sloppy. From a purist point of view, a try/catch would be more appropriate, since that constrains the return value to a single class of object.
Speaking of objects, using Exceptions doesn't rule out the ability to return objects - after all an Exception IS an object and can contain an arbitrarily complex collection of internal components. It's quite common for an Exception to contain both an integer error code and a message text, for example. For something like an XML parser, you might additionally add the source URL/filename, offending row and column, and active tag.
I hope I got all the mathematical terminology straight. I'm out of practice!
 
Mapraputa Is
Leverager of our synergies
Sheriff
Posts: 10065
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
except for "the set of cardinal numbers", probably
 
William Brogden
Author and all-around good cowpoke
Rancher
Posts: 13078
6
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
SOAP does this by returning a specialized fault object that can contain any serializable data such as a stack trace. All the client has to do is see if the returned object is an instance of
the fault object type, otherwise proceed normally. Seems to me this is the most flexible approach.
Bill
 
Jim Lang
Greenhorn
Posts: 27
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I have also heard the old 'don't use Exceptions for flow control' argument, which I can't say I understand, since the try..catch..finally block is there for a form of flow control anyway.
If anyone can explain the reasons for that caveat to me I would appreciate it.
Besides that I suppose I will go with the Object return type, although I feel that it definitely is not the most 'OO' solution. I would prefer the solution to include specific exceptions, but to preserve flexibility and to make sure that the interface does not change in future versions (only the javadoc changes) I shall opt for the former.
 
Steven Daniels
Greenhorn
Posts: 4
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Using exceptions for EXCEPTIONAL events will give you better performance. The virtual machine only has to execute exeption code when there is an exception. When an exception doesn't occur, the byte code that is the catch block is completely skiped. However if you use something like 'if instanceof Integer... else...' this must be executed each time you call the method (if there is an exception or not). The try/catch/finally blocks can take a little longer to run when there is an exception to catch, but it should be assumed that exceptions are bad, and as long as something bad has occured, we might as well take a little more time to handle it.
 
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!