Working with the Domain Driven Architecture - Revision history

Sichen at 17:13, 11 May 2010

2010-05-11T17:13:28Z

Sichen: /* Extending the Domains Directory */

2010-05-11T16:57:24Z

‎Extending the Domains Directory

Sichen: /* Extending the Domains Directory */

2010-05-11T16:54:50Z

‎Extending the Domains Directory

Sichen: /* Working with Entity Field Names */

2010-05-11T16:38:23Z

‎Working with Entity Field Names

Jwickers: /* Messages from Your Services */

2008-12-11T18:20:28Z

‎Messages from Your Services

Jwickers: /* Messages from Your Services */

2008-12-11T18:20:04Z

‎Messages from Your Services

Jwickers: /* Messages from Your Services */

2008-12-11T18:19:42Z

‎Messages from Your Services

Sichen at 17:44, 11 December 2008

2008-12-11T17:44:43Z

Jwickers: /* Working with Entity Field Names */

2008-12-10T18:39:46Z

‎Working with Entity Field Names

Sichen at 18:23, 10 December 2008

2008-12-10T18:23:01Z

← Older revision		Revision as of 17:13, 11 May 2010
Line 1:		Line 1:
		+	__TOC__
		+
	Here are some tips for working with the [[Domain Driven Architecture]]:		Here are some tips for working with the [[Domain Driven Architecture]]:
−	~~__TOC__~~

	====Instantiating Services and Repositories====		====Instantiating Services and Repositories====

← Older revision		Revision as of 16:57, 11 May 2010
Line 171:		Line 171:

	'''IMPORTANT''': You must not have two domains directory XML files of the same name, even if they are in different components.		'''IMPORTANT''': You must not have two domains directory XML files of the same name, even if they are in different components.
		+
		+	====For More Examples====
		+
		+	See <tt>org.opentaps.tests.domains</tt> package for examples of how to implement and use additional domains and alternative domains directories. The domains directory XML files are in <tt>opentaps/opentaps-tests/config/</tt>

← Older revision		Revision as of 16:54, 11 May 2010
Line 110:		Line 110:

	===Extending the Domains Directory===		===Extending the Domains Directory===
		+
		+	opentaps 1.5 and later give you the ability to extend the domains directory, so you can add additional domains or implement your own domains directory which overrides the default ones from opentaps. This can be helpful if your components want to use custom domains or implement additional domains which are not listed in the main opentaps domains directory.
		+
		+	To do this, implement your own DomainsLoader which extends the main <tt>org.opentaps.domains.DomainsLoader</tt>:
		+	public class AlternateDomainsLoader extends DomainsLoader {
		+
		+	Then, define your own domains directory file. This file could just define additional domains, such as this example from <tt>opentaps/opentaps-tests/config/test-domains-directory.xml</tt>:
		+	<beans>
		+	<bean id="testDomain" class="org.opentaps.tests.domains.TestDomain"/>
		+	</beans>
		+
		+	Or you can re-define all the domains again, to override the ones from opentaps, like in this example from <tt>opentaps/opentaps-tests/config/alternate-domains-directory.xml</tt>:
		+	<beans>
		+	<bean id="opentapsBillingDomain" class="org.opentaps.tests.domains.TestBillingDomain"/>
		+	<bean id="opentapsOrderDomain" class="org.opentaps.common.domain.order.OrderDomain"/>
		+	< !-- etc. etc -->
		+	<bean id="domainsDirectory" class="org.opentaps.domain.DomainsDirectory">
		+	<property name="billingDomain"><ref bean="opentapsBillingDomain"/></property>
		+	<property name="orderDomain"><ref bean="opentapsOrderDomain"/></property>
		+	< !-- etc. etc. -->
		+	</beans>
		+
		+	Then, in your custom domains loader's constructor, you can register additional domains directory XML files in the constructor:
		+	<pre>
		+	public static String TEST_DOMAINS_DIRECTORY = "test-domains-directory.xml";
		+
		+	public TestDomainsLoader(Infrastructure infrastructure, User user) {
		+	super(infrastructure, user);
		+	super.registerDomains(TEST_DOMAINS_DIRECTORY);
		+	}
		+	</pre>
		+
		+	If you want to switch from the main opentaps domains directory to your own, re-implement the <tt>getDomainsDirectory</tt> method to point to your domains directory file:
		+	<pre>
		+	public static String ALT_DOMAINS_DIRECTORY = "alternate-domains-directory.xml";
		+
		+	public DomainsDirectory getDomainsDirectory() {
		+	return super.getDomainsDirectory(ALT_DOMAINS_DIRECTORY);
		+	}
		+	</pre>
		+
		+	That's all there is to it. Now you can use the domains loader just as before:
		+	testDomain = domainsLoader.getDomainsDirectory().getDomain(TestDomainsLoader.TEST_DOMAIN);
		+	or
		+	billingDomain = alternateDomainsLoader.getDomainsDirectory().getDomain(DomainsDirectory.BILLING_DOMAIN);
		+
		+	and it will load the domains from your file.
		+
		+	====How Does It Work?====
		+
		+	The astute reader would have noticed that there is a slight difference in the code above for getting the domains. Instead of using
		+	domainsLoader.getDomainsDirectory().getBillingDomain();
		+
		+	We are now using
		+	alternateDomainsLoader.getDomainsDirectory().getDomain(DomainsDirectory.BILLING_DOMAIN);
		+
		+	The two are equivalent, but there are two changes in the internal architecture of the domains directory which permits the use of additional domains directory files and adding additional domains. The DomainsLoader now keeps a Map of domains directory file name -> DomainsDirectory, and the DomainsDirectory now keeps a map of name -> Domain. This is why you can now use the <tt>getDomain(String domainName)</tt> method to get your domain from the domain directory, and why you can add additional domains with a single <tt>bean</tt> definition.
		+
		+	Similarly, <tt>org.opentaps.domains.DomainsLoader</tt> now keeps a Map of domains directory file names and the corresponding DomainsDirectory. The <tt>getDomainsDirectory()</tt> method returns the domains directory located at the default opentaps domains directory file defined in <tt>DomainsLoader.DOMAINS_DIRECTORY_FILE</tt>. When you are implementing an alternative domains loader, you are just overriding <tt>getDomainsDirectory()</tt> with <tt>getDomainsDirectory(String domainsDirectoryFile)</tt> to load of domains directory in a different file.
		+
		+	'''IMPORTANT''': You must not have two domains directory XML files of the same name, even if they are in different components.

← Older revision		Revision as of 16:38, 11 May 2010
Line 108:		Line 108:
	Set productIdsInOrder = Entity.getDistinctFieldValues(items, OrderItem.Fields.productId);		Set productIdsInOrder = Entity.getDistinctFieldValues(items, OrderItem.Fields.productId);
	</pre>		</pre>
		+
		+	===Extending the Domains Directory===

@@ Line 70: / Line 70: @@
      setSuccessMessage("SuccessLabelA");
      serviceB();
-     // SuccessLabelB has overwritten the success message set
+     // SuccessLabelB has overwritten the success message
+}
 </pre>

@@ Line 34: / Line 34: @@
 Service can return success and error messages to the user.
-To return an error message simply throw a '''ServiceException''.
+To return an error message simply throw a '''ServiceException'''.
 To return a success message, you can use either '''setSuccessMessage''' or '''addSuccessMessage'''. The former is mean to return a single message whereas the later allows you to return a list of messages.

← Older revision		Revision as of 18:19, 11 December 2008
Line 31:		Line 31:

	====Messages from Your Services====		====Messages from Your Services====
		+
		+	Service can return success and error messages to the user.
		+
		+	To return an error message simply throw a '''ServiceException''.
		+
		+	To return a success message, you can use either '''setSuccessMessage''' or '''addSuccessMessage'''. The former is mean to return a single message whereas the later allows you to return a list of messages.
		+
		+	Each method supports localization by using labels that are translated into the user locale, refer to the API for more details.
		+
		+	For example:
		+	<pre>
		+	public void serviceA() throws ServiceException {
		+	try {
		+	// perform some modifications ...
		+	if (some error) {
		+	// return an error label, the second arguemnt is the context for substitution in the message
		+	throw new ServiceException("ErrorLabel", null);
		+	}
		+	} catch (SomeException e) {
		+	// generic error that you do not handle are also displayed back to the user
		+	// some exception are already localized (for example the RepositoryException related to not found entities)
		+	throw new ServiceException(e);
		+	}
		+	setSuccessMessage("SuccessLabel");
		+	}
		+	</pre>
		+
		+	Beware that nested direct service calls can override the success message, if you do not want that be sure to set it as the last instruction of the method.
		+
		+	<pre>
		+	public void serviceB() throws ServiceException {
		+	// perform some modifications ...
		+	setSuccessMessage("SuccessLabelB");
		+	}
		+
		+	public void serviceA() throws ServiceException {
		+	// perform some modifications ...
		+	setSuccessMessage("SuccessLabelA");
		+	serviceB();
		+	// SuccessLabelB has overwritten the success message set
		+	}
		+	</pre>
		+
		+	If you need to return a list of messages use '''addSuccessMessage''', and beware that '''setSuccessMessage''' will overwrite the list.
		+
		+	<pre>
		+	public void serviceB() throws ServiceException {
		+	// perform some modifications ...
		+	addSuccessMessage("SuccessLabelB");
		+	}
		+
		+	public void serviceA() throws ServiceException {
		+	// perform some modifications ...
		+	addSuccessMessage("SuccessLabelA");
		+	serviceB();
		+	// returns [SuccessLabelA, SuccessLabelB]
		+	}
		+	</pre>

	====Working with Entity Field Names====		====Working with Entity Field Names====

@@ Line 29: / Line 29: @@
      */
 </pre>
 ====Working with Entity Field Names====

← Older revision		Revision as of 18:39, 10 December 2008
Line 31:		Line 31:

	====Working with Entity Field Names====		====Working with Entity Field Names====
		+
		+	Each base entity has an enumeration listing its fields, and this enumeration is used in the framework API instead of using string literals. This means it is possible to use the IDE autocompletion but also that the resulting code is no longer at risk of resulting in runtime errors due to typos.
		+
		+	For example, when writing condition maps for the repository find methods, the repository provides a '''map''' method which allows you to write the map like this:
		+
		+	<pre>
		+	findOne(Order.class, map(Order.Fields.orderId, "WS10000"));
		+
		+	findList(OrderItemAssoc.class, map(OrderItemAssoc.Fields.orderId, "WS10000", OrderItemAssoc.Fields.orderItemSeqId, "00001"));
		+	</pre>
		+
		+	It is also used when retrieving distinct field values from a list, like for example:
		+
		+	<pre>
		+	List<OrderItem> items = findList(OrderItem.class, map(OrderItem.Fields.orderId, "WS10000"));
		+	Set productIdsInOrder = Entity.getDistinctFieldValues(items, OrderItem.Fields.productId);
		+	</pre>

← Older revision		Revision as of 18:23, 10 December 2008
Line 29:		Line 29:
	*/		*/
	</pre>		</pre>
		+
		+	====Working with Entity Field Names====