Clarify SQLInsertClause.executeWithKey() return value

[cowwoc]

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)]

This issue also affects the two executeWithKeys() methods.

[Timo Westkämper (timo-westkamper)]

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.

[Timo Westkämper (timo-westkamper)]

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)

[cowwoc (gili)]

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?

[Timo Westkämper (timo-westkamper)]

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

[Timo Westkämper (timo-westkamper)]

Released in 2.2.0-beta1

[Timo Westkämper (timo-westkamper)]

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)]

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.