JAVA api validation / Exception handling
How to Handle Error Conditions when Writing Java API / Utilities
This is my implementation for the API
public void bin2zip(InputStream[] is,OuputStream os, String[] names)
{
//if number of streams and number of names do not match do something
}
What I am trying to do is handle the case where the length is is
!=
length name
.
How can I handle this. I don't want my API to do some work until an exception is thrown ArrayOutOfBound
. I want to catch this sooner.
One solution looks like this:
If it doesn't match, I quit
if(is.length==names.length)
throws new Exception("ParemeterValidationException: The inputstream array and name array length should match");
if(containsInvalidFileName(names))
throws new Exception("ParemeterValidationException: The names array length should contain valid filenames");
Also, is it possible to do this by compiling time with DataDependency (I can make a ValidationClass for the API and make sure the developer grabs on to that object to get to that conversion API), or is a runtime exception the best way?
I believe doing ValidationClass will make the API tricky
I have looked through some materials (if anyone is interested), but several directions are needed.
source to share
If possible, don't let end users screw it on.
public final class Bin2Zipper {
private final List<InputStream> inputStreams = ...;
private final List<String> names = ...;
public BinZipper() {
}
public void add(final InputStream is, final String name) {
this.inputStreams.add(is);
this.names.add(name);
}
public void bin2zip(final OutputStream os) {
// ...
}
}
The fluent interface could be even better. Then your code will look like this:
Bin2Zipper.add(is1, name1).add(is2, name2).add(is3, name3).toZip(os);
public final class Bin2Zipper {
private final List<InputStream> inputStreams = ...;
private final List<String> names = ...;
private Bin2Zipper(final InputStream is, final String name) {
this.inputStreams.add(is);
this.names.add(name);
}
public static Bin2Zipper add(final InputStream is, final String name) {
return new Bin2Zipper(is, name);
}
public Bin2Zipper add(final InputStream is, final String name) {
this.inputStreams.add(is);
this.names.add(name);
return this;
}
public void zip(final OutputStream os) {
...
}
}
Where do they fall when the client starts with two arrays. In this case, they may be annoyed that they have to iterate over all the records on their own. I think it's still worth it. If you don't, you will need to immediately compare the sizes of the inputs. You almost certainly want to throw an unchecked exception, perhaps IllegalArgumentException
as Vince said.
source to share
I think your solution for comparing the length of arrays is fine. I think in this case you should throw an IllegalArgumentException; this exception is defined in the standard and is used by most of the standard functions that perform this check.
Many standard libraries use this kind of interface, which is easy to understand.
This suggests that you should prefer an interface that just doesn't encourage as much misuse as @Eric suggested - the library everyone loves to use is the one that works every time every time because it's too easy to screw up ...
source to share