File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
http://aspose.com/file-tools
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes Nx: Documenting DuplicateKeyException Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "Nx: Documenting DuplicateKeyException" Watch "Nx: Documenting DuplicateKeyException" New topic
Author

Nx: Documenting DuplicateKeyException

Tony Collins
Ranch Hand

Joined: Jul 03, 2003
Posts: 435
In my opinion DuplicateKeyExeption in Bodgitt and Scarper, can never be thrown, will never be thrown and should not be in the DBAccess Interface.
But it is, so in my Javadoc documentation do I document that this impossible exception could be thrown as the interface sugests and confuse the reader of the API or do I ignore it and confuse any programmer reading the code ?
Tony
Jim Yingst
Wanderer
Sheriff

Joined: Jan 30, 2000
Posts: 18671
I'd document that the current implementation does not throw any DuplicateKeyException, but it's a possible future enhancement if someone at Bodgitt & Scarper gets off their lazy ass and provides some sort of evidence that the file actually should have a primary key. (And what is it? And what to do about the crappy update() method?)
Well, don't use those words exactly. But do document it, both in the Data API and in the design decisions document.


"I'm not back." - Bill Harding, Twister
Mark Spritzler
ranger
Sheriff

Joined: Feb 05, 2001
Posts: 17250
    
    6

I thought in the Contractor assignment that there is a primary key. It was the Contractor name in my Beta, but even if that is no longer, the contractor name and location would still make up a primary key.
I for one will always believe that a Create method should throw a DuplicateKeyException.
Mark


Perfect World Programming, LLC - Two Laptop Bag - Tube Organizer
How to Ask Questions the Smart Way FAQ
Tony Collins
Ranch Hand

Joined: Jul 03, 2003
Posts: 435
My contractor exam doesn't mention a primary key, can you assume the DB has a primary key and that it is one particular combination of fields.
Tony
Jim Yingst
Wanderer
Sheriff

Joined: Jan 30, 2000
Posts: 18671
I thought in the Contractor assignment that there is a primary key. It was the Contractor name in my Beta, but even if that is no longer, the contractor name and location would still make up a primary key.
I'll agree that name + location could be used as a primary key, but the instructions provide very little info to support this. Here's all I have found to support the idea that name + location should be a primary key:
  • As noted, the create() method is listed as "throws DuplicateKeyException". No further explanation; the only other place the word "key" appears in the instructions is in the phrase "There are three key parts...".
  • Under "The User Interface", we are told: "It must allow the user to search the data for all records, or for records where the name and/or location fields exactly match values specified by the user." Indicating a special status for name and location. But no indication that this combination needs to be unique.
  • Examining the included DB file itself, it appears that while name is not unique, and location is not unique, name + location is indeed unique for included entries.

  • There's one more factor which is outside the instructions completely - our "common sense" tells us that a database should have some sort of primary key, other than the record number. Well, maybe so, but my common sense tells me Bodgitt & Scarper will eventually need a lot of other things too, if this were to become a serious database system. I keep having to remind myself (or be reminded by others) that those things aren't actually required for this assignment.
    The case against implementing a uniqueness constraint on name + location, IMO, is:
  • It's never explicitly required.
  • It's more work.
  • It would add complexity. (Not necessarily a huge amount, it could be isolated, but still...)
  • It would decrease performance. (Again, not a big concern, but it's there.)
  • The update() method does not throw DuplicateKeyException, even though it's fully capable of changing the name and location fields. I suppose that it's less necessary here because a competent programmer can simply avoid ever changing those fields in an update - while for create() they have to provide values, and don't know if those values are already in teh DB or not. (Even a find() is insufficient to make any guarantees here unless you block all other create() calls between the find() and your create(). Possible but icky.) Still, failure to address the update() issue is a big indicator (for me) that whoever wrote the DuplicateKeyException part of the API was probably on crack.
  • The DB file header does not provide any way to indicate primary keys. If we ignore possibility of primary keys, then the Data class can provide nice generic access to any file implementing the given format - not just B&S contractor info. Adding a uniqueness restriction would thus limit reusability of the Data class.
  • The GUI client we're actually delivering here is not capable of doing any create(), or update() of any field other than client ID, so there's no possibility of actually creating any duplicate keys with this software. If some future enhancement needs to make use of the create() and update() methods, then at that time someone can get B&S to clarify what they really wanted, and make modifications to the Data class (and hopefully DB as well) if necessary.

  • So - while it seems very plausible that enforcing a unique primary key might be a future enhancement, I don't think it's necessary, or even a good idea, to do it now.
    [ July 29, 2003: Message edited by: Jim Yingst ]
    Mark Spritzler
    ranger
    Sheriff

    Joined: Feb 05, 2001
    Posts: 17250
        
        6

    And excpet for the fact that this was written for you. In the Fly By Night assignment there was no mention in the instructions.html about a primary key. But looking at the code that was provided you saw that flight number was used as the primary key.
    I like Jim's thoughts about common sense. It should be common sense that there is a primary key and which fields are combined to make a rpimary key.
    The Hotel reservation assignment is a whole nother question.
    Mark
    Jamie Orme
    Greenhorn

    Joined: Apr 24, 2003
    Posts: 22
    Guys
    I did create a primary key on name and location, and included checks in both the update and create methods. The update method catches DuplicateKeyException and then using exception chaining passes it on as a RecordNotFoundException.
    I defined the key in a ContractorSchema class which extended an abstract Schema class. The Schema class, in addition to reading in meta-data, contained an abstract method:


    The ContractorSchema class provided an implementation for this, and thus allowed the Data class to remain generic as it could be created with any Schema class defined (say in the future a CustomerSchema class).
    I did get full marks for my Data class, but that doesnt mean to say you should do as I did. I just thought there should be a primary key, so I implemented one and then documented it. My extra effort may well have been overkill.....
    Cheers
    Jamie
    [ July 29, 2003: Message edited by: Jamie Orme ]
    [ July 29, 2003: Message edited by: Jamie Orme ]
    Jim Yingst
    Wanderer
    Sheriff

    Joined: Jan 30, 2000
    Posts: 18671
    The Hotel reservation assignment is a whole nother question.
    I did get that impression when looking at past dicussions of DuplicateKeyExceptions. Many of the dicussions become hopelessly confusing to me as some people talk about contractors, others talk hotels, and others talk flights. Many aspects of these assignments seem interchangeable, but I think the DuplicateKeyException many be an exception to this. So, let's try to keep this particular thread to Contractors only. Other topics can start new threads, or revive old ones. Thanks.
    On rereading, that looks a bit like a reprimand of Mark, which is not the intent. I have no problem with his comments. I just don't want other people to now start arguing the details of Hotels here, because that just confuses me.
    Jim Yingst
    Wanderer
    Sheriff

    Joined: Jan 30, 2000
    Posts: 18671
    Jamie - cool, I like that implementation. I may tweak my deign to better support something like that as a future enhancement.
    Do we have anyone here who completed Contractors without using any primary key, and can report how that was graded?
     
    It is sorta covered in the JavaRanch Style Guide.
     
    subject: Nx: Documenting DuplicateKeyException