[e4-dev] API-Design Questions

[Tom Schindl <tom.schindl@xxxxxxxxxxxxxxx>]

Hi,

I've added a new method today to the EPartService which has the
following JavaDoc

-----------8<-----------
> /**
> 	 * Returns a collection of all {@link MInputPart} with the inputURI-Attribute set to the given
> 	 * value
> 	 * 
> 	 * @param inputUri
> 	 *            the input uri to search for, must not be <code>null</code>
> 	 * @return list of parts or an empty collection
> 	 */
> 	public Collection<MInputPart> getInputParts(String inputUri);
-----------8<-----------

As you'll see the method specs that NULL is not an allowed value. Now I
think we should define what writing methods like this means.

Question: Should it throw a RuntimeException?

Question: if yes which one:
 * IllegalArgumentException
 * org.eclipse.core.runtime.AssertionFailedException
 * NullPointerException

Question: and should it be document in the JavaDoc like this:
-----------8<-----------
> /**
> 	 * Returns a collection of all {@link MInputPart} with the inputURI-Attribute set to the given
> 	 * value
> 	 * 
> 	 * @param inputUri
> 	 *            the input uri to search for, must not be <code>null</code>
> 	 * @return list of parts or an empty collection
> 	 * @throws IllegalArgumentException
> 	 *             if null passed as argument
> 	 */
> 	public Collection<MInputPart> getInputParts(String inputUri);
-----------8<-----------

My proposal is that we define that we throw an IAE (because then the API
uses standard JDK-Classes) and document it in the JavaDoc.

Tom

-- 
B e s t S o l u t i o n . a t                        EDV Systemhaus GmbH
------------------------------------------------------------------------
tom schindl                                        geschaeftsfuehrer/CEO
------------------------------------------------------------------------
eduard-bodem-gasse 5/1    A-6020 innsbruck      phone    ++43 512 935834