[jsword-devel] Patch for java/swing

[DM Smith]

Joe Walker wrote:

>
>
>I've checked this in.
>There are a couple of things I'd like to spend more time on tomorrow. I've 
>not had time to think about the changes to deprecate the String ctor on 
>LucidException which affects RemoteException. A brief glance said that you 
>had considered the need for literal strings there but I need to look more.

The only reason to add @deprecated is to clearly mark what needs to be 
internationalized.
If we want to tackle it later we can add it then and only while we do the 
work.

>Second, Isn't it useful to have Reporter able to display any Exception? I 
>commented out the @dep because I was getting warnings everywhere and wasn't 
>sure why.

The Reporter will display the message of any Exception that it is given. The 
problem that I see is twofold:
1) The messages of exceptions traditionally are meant for programmers and 
not end users of applications. They are often terse and refer to some inner 
knowledge of the code.
2) The messages are not internationalized, which is fine for me, but I speak 
English.

Exceptions are a powerful programming mechanism that can capture program 
state (i.e. call stack) and the reason for the failure at the point it 
failed (i.e. message). However, the message created at the point of failure 
is not necessarily the one the user should see.

For example the messages that JAXB gives are very good for a developer to 
understand what is going on. But when the message gives part of the internal 
representation of the document that it is choking on and some cryptic (to a 
Bible student) message saying that it "did not recognize the resp element", 
that is just not helpful. It is useful in the details, but not as the 
primary message.

So I added that EventException and LucidException, which are deliberate 
exceptions that we create with messages that we invent (and hopefully 
internationalize), to Reporter so that it would make sense to a 
non-programmer.

The deprecations merely indicate that Reporter is called a bunch of times 
with the exception that the program caught. What we should do is wrap the 
exception in a LucidException or an EventException and give it a clear 
message related to the work that was being attempted by the user.

This means two things first we don't give the message down deep in the code, 
but give it near to the action that the user performed. Second, we give it a 
message that is geared to the end user.

This can be accomplished with the following pattern (contrived example):
in Msg.java
static final Msg BAD_PASSAGE_DATA = new Msg("The Sword Module has garbled 
text in it and we could not get the passage you wanted.")
in some part of desktop:
try
{
    assert thePassage != null; // since I learned about these today, I had 
to throw one in
    renderPassage(thePassage);
}
catch (Exception e) // any exception w/o knowing what it is about
{
    Reporter.invoke(getDesktop().getJFrame(), new 
LucidException(Msg.BAD_DATA, e));
}
>
>Thanks for the patch anyway I'm once again very impressed.
>
>You even followed my convention of spelling swing as sw*ng outside of 
>classes that are in the swing tree so we can check for swing dependencies 
>with a recursive grep, to help us work in headerless environments. 11 out 
>of 10!
>
>Joe.
>
>DM Smith wrote:
>>I have included a patch which does the following:
>>
>>Modified EventException to mimic LucidException. Joe, you should rename 
>>EventException to something like LucidCheckedException.
>>
>>Marked methods in LucidException that took strings as arguments as 
>>deprecated. (Identifies i18n problems)
>>
>>Added methods to reporter to take a MsgBase and optionally params, and 
>>methods that take EventException and LucidException.
>>
>>Marked methods in Reporter that took Throwable as deprecated. (Identifies 
>>i18n problems)
>>
>>Remove the ctor from EventException that took a String. This required 
>>adding Msg.java to .../common/config/swing and using it in 
>>ConfigEditorFactory.
>>
>>In jsword/view/swing/desktop:
>>    I moved all strings (except that which should be converted to actions) 
>>that should be internationalized to Msg.
>>    I moved all other strings to private static final String declarations.
>>    I removed all dead inner classes related to AbstractActions. (also did 
>>this to SitesPane)
>>    I added the ability to open the config dialog from DesktopActions.
>>    I removed member variables which did not need to exist.
>>    I made the showing of debug tab optional on the About screen.
>>    I added the ability to do the same for all the other advanced stuff on 
>>the About dialog. It needs to be tied into config.xml for it to do 
>>something.
>>
>>The following code is not used by the JSword GUI and could be removed 
>>(unless it is there for future use):
>>     ComparePane
>>     CompareResultsPane
>>     DesktopAbstractAction
>>     GeneratorPane
>>     MaintenancePane
>>     LogPane
>>     ComponentAbstractAction (if we get rid of LogPane)
>>     EirAbstractAction (if we get rid of ComponentAbstractAction and 
>>DesktopAbstractAction)
>>     EirPanel (if we get rid of LogPane, GeneratorPane, MaintenancePane, 
>>ComparePane)
>>There may be tests that exercise these.
>>
>>_________________________________________________________________
>>Persistent heartburn? Check out Digestive Health & Wellness for 
>>information and advice. http://gerd.msn.com/default.asp
>
>
>_______________________________________________
>jsword-devel mailing list
>jsword-devel@crosswire.org
>http://www.crosswire.org/mailman/listinfo/jsword-devel

_________________________________________________________________
Check out MSN PC Safety & Security to help ensure your PC is protected and 
safe. http://specials.msn.com/msn/security.asp