The Java API is completely safe as long as it's used in a separate application and is not tied to a trigger script. So for example, if you create a Java application that periodically checks / modifies items then that's completely safe (as long as that application is not started by a trigger script).
The problem with using the API from within a trigger script is that the API action appears as though it is performed by a different user. Since only 1 user can edit an item at a time, all subsequent edits to an item wait for any existing edits to complete. As an example, If the script attempts to edit the very same item that is being edited but through the API then that API call will never complete (because it's waiting for the current edit to complete) and the script will never complete because it's waiting for the API call to complete so you have a deadlock.
You can use the insertSegment method on the ScriptIssueDeltaBean speficying the reference mode but this is just for inserting segments (not for editing existing ones).
There is the "im toggleinclude" CLI command which can theoretically be run through the API however this has not been officially published (/certified) and only published API commands are supported by PTC for use with the Integrity API. Please see the Integrations Builder Guide for more details about published (/certified) commands.
Please open a new case if you have any further questions about this.
Regards,
Dan Rusu
