[jboss-dev-forums] [Embedded JBoss Development] - Re: Embedded API Design Problems

[ALRubinger]

Thanks for the feedback, Richard.  We're at Alpha-level to encourage this kind of discussion.

"richard.opalka at jboss.com" wrote : INCONSISTENT METHOD NAMES
  | API should be consistent. Once you're following BEAN naming convention, whole API must apply to this rule. 

I'm not strictly following bean conventions.  For the method chaining signatures, I considered Fowler's note on command query separation as detailed in http://martinfowler.com/dslwip/MethodChaining.html.

"richard.opalka at jboss.com" wrote : DO NOT DECLARE TO THROW RUNTIME EXCEPTIONS

I'm a big fan of declared unchecked exceptions; they more completely document the API.  I don't care if the exception thrown is in a different package (eg Rule 2.2 "FileOutputStream.write(byte[]) throws ArrayIndexOutOfBoundsException").  Rule 2.3, consistency, is a design goal and any places that do not follow this need to be ironed out; which did you mean in particular?  In order to act upon rule 2.4, forcing the user to deal w/ checked exceptions, I'll need some examples you believe need attention.  I don't agree with Rule 2.5.

>From where are you deriving these rules BTW?

"richard.opalka at jboss.com" wrote : INCONSISTENT ENUM VALUES

"PRE_INIT" seemed more descriptive to me; it's fired *before* initialization is called.  Your suggestion to "INITIALIZING" isn't accurate as the server is not in the process of actually initializing; perhaps we should go to "PRE_INITILIZATION" or similar?

"richard.opalka at jboss.com" wrote : INCONSISTENT API ABSTRACTION
  | 
  | Instead of throwing low level exception API designer should create exception that is consistent with API abstraction.
  | In many cases such main abstraction exception don't need to be specified in throws clausule (just throw it). 

I don't consider Java Platform exceptions to be unnecessarily low-level; in fact Bloch encourages their use in validating preconditions/postconditions (I'd make a reference here but don't have my book w/ me).  These are well-known APIs which programmers are likely to know already.  Why wrap these in some Embedded-specific API?  IllegalArgumentException and InstanciationException means exactly that.

"richard.opalka at jboss.com" wrote : OTHER CODE INCONSISTENCIES

I don't see how the generics issue you point out is an inconsistency.  Also "other inconsistencies" doesn't help find action items. :)

S,
ALR



View the original post : http://www.jboss.org/index.html?module=bb&op=viewtopic&p=4268821#4268821

Reply to the post : http://www.jboss.org/index.html?module=bb&op=posting&mode=reply&p=4268821