Clarify SQLInsertClause.executeWithKey() return value

Bug #732409 reported by cowwoc on 2011-03-10
6
This bug affects 1 person
Affects Status Importance Assigned to Milestone
Querydsl
Fix Released
Undecided
Unassigned

Bug Description

The documentation for SQLInsertClause.executeWithKey() should clarify that the method returns null if the insert operation fails.

Also, It's not clear when the insert operation may fail nor how users can find out the underlying cause if this occurs.

cowwoc (gili) wrote :

This issue also affects the two executeWithKeys() methods.

I'd prefer to keep the current semantics and just document it. With a real failure you get an SQLException, otherwise just a null result.

I just updated the documentation :

    /**
     * Execute the clause and return the generated key with the type of the given path
     * If no rows were created, null is returned, otherwise the key of the first row is returned.
     *
     * @param <T>
     * @param path
     * @return
     */
    @Nullable
    public <T> T executeWithKey(Path<T> path)

    /**
     * Execute the clause and return the generated keys with the type of the given path.
     * If now rows were created and empty list is returned.
     *
     * @param <T>
     * @param path
     * @return
     */
    public <T> List<T> executeWithKeys(Path<T> path)

Changed in querydsl:
status: New → Fix Committed
cowwoc (gili) wrote :

Hi Timo,

1. Please document the exception you referred to. I see no @throws in the above Javadoc.
2. It's not clear why an insert would result in no rows being created. Can you give an example?

1. Yes, sorry, this was not specific enough, the Exceptions are unchecked, but I will document this better
2. I am sure you can do that with an "insert into ... select ..." clause

Released in 2.2.0-beta1

Changed in querydsl:
status: Fix Committed → Fix Released

Checked Exceptions in Querydsl are minimized and not all unchecked Exceptions are documented. As a general rule checked Exceptions from database are wrapped into QueryException instances.

cowwoc (gili) wrote :

1. I'm fine with unchecked exceptions so long as they are documented. I think it especially makes sense in this case because users will be asking "what happens if my insert violates a constraint? What will this method do?".
2. Thank you for the clarification. I wasn't aware of "insert into ... select ..." until just now. It makes perfect sense.

To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers