[SWS-443] Javadoc State Thread Safety Level PayloadEndpoint Implementers Must Support Created: 31/Oct/08  Updated: 04/May/12  Resolved: 01/Nov/08

Status: Closed
Project: Spring Web Services
Component/s: Documentation
Affects Version/s: 1.5.4
Fix Version/s: 1.5.5

Type: Improvement Priority: Major
Reporter: Brian Brooks Assignee: Arjen Poutsma
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

Please update the JavaDoc for org.springframework.ws.server.endpoint.PayloadEndpoint to explicitly state the level of thread safety it supports. See reference below. After reading through the spring-ws reference manual and forums, I think I've confirmed that endpoint instances are shared by multiple threads (one thread per request).

Wellings "Concurrent and Real-Time Programming" section 4.8, document's Bloch's Thread Safety Levels...

"To aid the construction of concurrent Java programs, it is necessary for classes to document clearly the level of thread safety they support. Bloch (Bloch, 2001) has suggested the following levels:
• Immutable. Instances of the class are constant and cannot be changed. There are, therefore, no thread safety issues. The String class is a good example of an immutable class.
• Thread-safe. Instances of the class are mutable but they can be used safely in a concurrent environment. All methods provided by the class are properly synchronized either at the interface level or internally within the method. The java.util.Timer class presented in Section 4.4 is an example of a thread-safe class with internal synchronization.
• Conditionally thread-safe. Instances of the class either have methods that are thread-safe or have methods that are called in sequence with the lock held by the caller. The SharedCoordinate class given in Section 3.1 is an example of a conditionally thread-safe class.
• Thread-compatible. Instances of the class provide no synchronization. However, instances of the class can be safely used in a concurrent environment, if the caller provides the synchronization by surrounding each method (or sequence of method calls) with the appropriate lock.
• Thread-hostile. Instances of the class should not be used in a concurrent environment even if the caller provides external synchronization. Ideally, classes should not be written that are thread-hostile. Typically a thread-hostile class is accessing static data or the external environment."



 Comments   
Comment by Brian Brooks [ 31/Oct/08 ]

Adding the same information to the JavaDoc for

org.springframework.ws.client.support.interceptor.ClientInterceptor
org.springframework.ws.server.EndpointInterceptor

would be great too.

Comment by Arjen Poutsma [ 01/Nov/08 ]

PayloadEndpoint is an interface, I cannot define the level of thread safety it supports. That really depends on the implementing class. That said, any endpoint (as any other Spring Bean) is scoped as a singleton by default, i.e. one instance of the bean definition is created per container. Being a singleton implies that more than one thread can use it, so it has to be thread safe. If you want to use a different scope, such as prototype, see

http://static.springframework.org/spring/docs/2.5.x/reference/beans.html#beans-factory-scopes

I will also add a little note to the documentation about endpoints being Spring singletons by default. Also, all abstract base classes (like AbstractDomPayloadEndpoint etc) are thread safe.

Comment by Arjen Poutsma [ 04/May/12 ]

Closing old issues

Generated at Sun Dec 17 11:53:42 UTC 2017 using JIRA 6.4.14#64029-sha1:ae256fe0fbb912241490ff1cecfb323ea0905ca5.