PageRenderTime 102ms CodeModel.GetById 60ms app.highlight 1ms RepoModel.GetById 40ms app.codeStats 0ms

/src/CommonServiceLocator/lib/Readme.txt

http://github.com/philiplaureano/LinFu
Plain Text | 71 lines | 36 code | 35 blank | 0 comment | 0 complexity | 09a5f97da89acc93dac4e1365aa14999 MD5 | raw file
 1This file explains the expected semantics IServiceLocator implementations must implement to properly conform to this interface, and a few implementation notes.
 2
 3==== Specification ====
 4
 5**** GetInstance(Type, string) ****
 6
 7This is the core method for retrieving a single instance from the container.
 8
 9This method MUST NOT return null. It MUST return either an instance that implements the requested type or throw an ActivationException.
10No other exception type is allowed (except for the usual CLR rules for things like ThreadAbortException).
11
12The implementation should be designed to expect a null for the string key parameter, and MUST interpret this as a request to get the "default" instance for the requested type. The meaning of "default" depends on the underlying container and how it is configured. A string of length 0 is considered to be different from a null, and implementers are free to choose what a string of length 0 as a key means.
13
14**** GetAllInstances(Type) ****
15
16This is the core method for retrieving multiple instances from the container.
17
18If the container contains no instances of the requested type, this method MUST return an enumerator of length 0 instead of throwing an exception.
19
20If an exception occurs while activating instances during enumeration, this method SHOULD throw an ActivationException and abort the enumeration. However, it may also choose to simply skip that object and continue enumerating.
21
22**** Overload Behavior ****
23
24A call to:
25
26    object IServiceLocator.GetInstance(serviceType)
27    
28MUST be exactly equivalent to a call to:
29
30    object IServiceLocator.GetInstance(serviceType, null)
31    
32A call to:
33
34    TService IServiceLocator.GetInstance<TService>()
35
36MUST be exactly equivalent to a call to:
37
38    (TService)IServiceLocator.GetInstance(typeof(TService), null)
39    
40A call to:
41
42    TService IServiceLocator.GetInstance<TService>(key)
43    
44MUST be exactly equivalent to a call to:
45
46    (TService)IServiceLocator.GetInstance(typeof(TService), key)
47    
48A call to:
49
50    IEnumerable<TService> IServiceLocator.GetAllInstances<TService>()
51    
52Must be exactly equivalent to a call to:
53
54    IEnumerable<object> IServiceLocator.GetAllInstances(typeof(TService))
55    
56with the exception that the objects returned by the enumerator are already cast to type TService.
57
58**** Throwing ActivationException ****
59
60When throwing an ActivationException, the message string is explicitly undefined by this specification; the adapter implementors may format this message in any way they choose.
61
62When throwing an ActivationException, the original exception MUST be returned as the value of the InnerException property.
63
64==== ServiceLocatorImplBase ====
65
66This class is not part of the specification; consumers should only reference the IServiceLocator interface. ServiceLocatorImplBase is provided as a convenience for implementors of IServiceLocator. It implements the correct overload semantics and exception wrapping behavior defined above. You just need to implement the two protected methods DoGetInstance and DoGetAllInstances and the rest will just work. In addition, the two protected methods FormatActivationExceptionMessage and FormatActivateAllExceptionMessage are provided if you wish to customize the error message reported in the exceptions.
67
68==== Why is ActivationException a partial class? ====
69
70Implementing ISerializable for exceptions is a .NET best practice for the desktop CLR. However, I anticipate a port to Silverlight for this code - many containers are already supporting Silverlight beta 2 or are about to. Silverlight does not support classic binary serialization. By making this a partial class and segregating the serialization details into a separate file, a future Silverlight port can simply leave the .Desktop.cs file out of the project and the incompatible code will be seamlessly removed.
71