Tutorial: Creating a Service - Revision history

Arnofiva: typo

2008-06-16T23:14:45Z

typo

Paulb: /* Creating a Service Interface */

2008-05-14T22:49:02Z

‎Creating a Service Interface

Paulb: /* Overview */

2008-05-14T22:34:18Z

‎Overview

Paulb at 16:57, 1 October 2007

2007-10-01T16:57:22Z

Paulb: /* Next Steps */

2007-09-28T22:45:23Z

‎Next Steps

Paulb: /* Next Steps */

2007-09-28T22:45:11Z

‎Next Steps

Paulb: /* Proffering a Service */

2007-09-28T22:35:21Z

‎Proffering a Service

Paulb: /* Implementing the Service Routines */

2007-09-28T22:01:25Z

‎Implementing the Service Routines

Paulb: /* Implementing the Service Routines */

2007-09-28T21:55:16Z

‎Implementing the Service Routines

Paulb: /* A Log Event Item Implementation */

2007-09-28T21:36:56Z

‎A Log Event Item Implementation

@@ Line 12: / Line 12: @@
 == Overview ==
-This tutorial will showing you how to create a service logger service, used to log messages. The logger service will actually be a simplied version of the longger service already available in [[EiffelStudio]], <e>LOGGER_S</e>.
+This tutorial will showing you how to create a service logger service, used to log messages. The logger service will actually be a simplied version of the logger service already available in [[EiffelStudio]], <e>LOGGER_S</e>.
 The tutorial will cover creating and implementing a service, registering a service, adding eventing and finally consuming the service and using an service observer.

@@ Line 19: / Line 19: @@
 == Creating a Service Interface ==
-The very first step in creating a service is to define a service interface. A service interface should contain either all deferred routines or deferred routines with only effective routines that reference the service interface directly or other interfaces in the [[EiffelStudio]] [[EiffelStudio Ecosystem|ecosystem]].
+The very first step in creating a service is to define a service interface. A service interface should contain only deferred routines or deferred routines with effective routines that only reference the service interface directly or other interfaces in the [[EiffelStudio]] [[EiffelStudio Ecosystem|ecosystem]].
-{{Note|It is important to realize that the interface abstraction allows for complete freedom to be given to the implementation of the service. Implementation details are not public and should remain that way. No consumer of the service should ever attempt to reverse assign a retrieve service to the implementation class but to the interface class. Consumer of the service should not have to rely on the implementation details of a service and doing so will potentially break code in the future or if a different implementation is returned than expected when querying to a specific service.}}
+{{Note|It is important that the interface abstraction allows for complete freedom to be given to the implementation of the service. Implementation details are not public and should remain that way. No consumer of the service should ever attempt to reverse assign a retrieve service to the implementation class but to the interface class. Consumer of the service should not have to rely on the implementation details of a service and doing so will potentially break code in the future or if a different implementation is returned than expected when querying to a specific service.}}
 This tutorial is creating a logger service so it makes senses we should create a service interface class call <eiffel>LOGGER_SERVICE_S</eiffel>. Create a deferred class <eiffel>LOGGER_SERVICE_S</eiffel> in your extension project cluster.
-{{Note|All service interfaces, by convention, are suffixed <eiffel>_SERVICE_S</eiffel>. This makes it clear to a consumer that they are using a service interface. All other related interfaces for the service should be suffixed <eiffel>_I</eiffel> to indicate an interface.}}
+{{Note|All service interfaces by convention are suffixed <eiffel>_S</eiffel>. This makes it clear to a consumer that they are using a service interface. All other related interfaces for the service should be suffixed <eiffel>_I</eiffel> to indicate an interface.}}
-The first step is to define <eiffel>LOGGER_SERVICE_S</eiffel> as an actually service. In order to achieve this <eiffel>LOGGER_SERVICE_S</eiffel> must inherit <eiffel>SERVICE_I</eiffel>. As of EiffelStudio 6.1 <eiffel>SERVICE_I</eiffel> does not contain any effective or deferred routines, it's merley a place holder for future additions and a method of classification.
+The first step is to define <eiffel>SIMPLE_LOGGER_S</eiffel> as an actually service interface. In order to achieve this <eiffel>SIMPLE_LOGGER_S</eiffel> must inherit a service base interface <eiffel>SERVICE_I</eiffel>. As of [[EiffelStudio]] [[EiffelStudio 6.1 Releases|6.1]] <eiffel>SERVICE_I</eiffel> does not contain any effective or deferred routines, it is merely a place holder for future additions and a method of classification. It does however inherit another service class <e>SITE</e>, which will be talked about it later.
 So now you should have something looking like this:
-<eiffel>
+<e>
 deferred class
-    LOGGER_SERVICE_S
+  SIMPLE_LOGGER_S
 inherit
-    SERVICE_I
+  SERVICE_I
 end
-</eiffel>
+</e>
-Of course this doesn't do all that much, in fact it does nothing! We need to add a way to log messages. For this we'll add <eiffel>put</eiffel> routines; <eiffel>put_message</eiffel> and <eiffel>put_message_with_severity</eiffel>.
+Of course this doesn't do all that much, in fact it does nothing! We need to add a way to log messages. For this we'll add <e>put</e> routines; <e>put_message</e> and <e>put_message_with_severity</e>.
-A logger shouldn't just simply log a message, it's just not powerful enough. So the put routines for the service should permit categorization and even indicate a level of severity incase a logger service consumer deems that a particular entry deserves more or less attention. Fortunatly Griffin offeres built in support for categorization and a basic priority level, which will serve quite nicely as a translation for a log item severity level.
+A logger shouldn't just simply log a message, it's just not powerful enough. So the put routines for the service should permit categorization and even indicate a level of severity in case a logger service consumer deems that a particular entry deserves more or less attention. Fortunately ESS offers built in support for categorization and a basic priority level, which will serve quite nicely as a translation for a log item severity level.
 === Categories and Priorities ===

@@ Line 12: / Line 12: @@
 == Overview ==
-IN this tutorial we'll be showing you how to create a service use to log messages. Although the service contains a simple interface, it's actually quite complete in that the service itself will make use of the [[Event List Service]] as a demonstration how reusing services in [[EiffelStudio]] can make development strategies quicker and easier.
+This tutorial will showing you how to create a service logger service, used to log messages. The logger service will actually be a simplied version of the longger service already available in [[EiffelStudio]], <e>LOGGER_S</e>.
 == Creating a Service Interface ==

← Older revision		Revision as of 16:57, 1 October 2007
Line 1:		Line 1:
		+	[[Category:Extending EiffelStudio]]
		+	[[Category:EiffelStudio Services]]
		+	{{UnderConstruction}}
	In this tutorial I'll demonstrate the process for integrating third-party [[EiffelStudio_Service\|services]] inside [[EiffelStudio]] and hooking up internal parts of [[EiffelStudio]] to use the new service.		In this tutorial I'll demonstrate the process for integrating third-party [[EiffelStudio_Service\|services]] inside [[EiffelStudio]] and hooking up internal parts of [[EiffelStudio]] to use the new service.

@@ Line 546: / Line 546: @@
 With the all the code in place, the logger service is read to be interacted with. In the [[Tutorial: Consuming a Service|next tutorial]] on [[Services|services]] we will put the logger service to use in existing functionality in EiffelStudio.
-In the [[Tutorial: Creating a Service-Based Tool|final tutorial]] we'll explorer using [[EiffelStudio Foundataions]] to create a dockable Eiffel tool to display the logged messages.
+In the [[Tutorial: Creating a Service-Based Tool|final tutorial]] we'll explorer using [[EiffelStudio Foundations]] to create a dockable Eiffel tool to display the logged messages.
 == SVN Patch ==
 For the full tutorial code, please grab an SVN patch from [[here]].

← Older revision		Revision as of 22:45, 28 September 2007
Line 547:		Line 547:

	In the [[Tutorial: Creating a Service-Based Tool\|final tutorial]] we'll explorer using [[EiffelStudio Foundataions]] to create a dockable Eiffel tool to display the logged messages.		In the [[Tutorial: Creating a Service-Based Tool\|final tutorial]] we'll explorer using [[EiffelStudio Foundataions]] to create a dockable Eiffel tool to display the logged messages.
		+
		+	== SVN Patch ==
		+	For the full tutorial code, please grab an SVN patch from [[here]].

← Older revision		Revision as of 22:35, 28 September 2007
Line 517:		Line 517:
	That's it! Coming this far you have created all of the interfaces and implementation needed to use the service. All that's left to do now is to proffer the service so other tools and services can make use of the logger service.		That's it! Coming this far you have created all of the interfaces and implementation needed to use the service. All that's left to do now is to proffer the service so other tools and services can make use of the logger service.

−	== Proffering and ~~Revoking~~ a Service ==	+	== Proffering a Service ==
		+	To permit access to the logger service you need to register the service with a [[Service#Service Containers\|service container]. Typically most [[Service\|services]] in [[EiffelStudio]] will be registered in <eiffel>ES_ABSTRACT_GRAPHIC.add_core_services</eiffel>.
		+
		+	In <eiffel>ES_ABSTRACT_GRAPHIC.add_core_services</eiffel> add the following line of code to register the logger service.
		+
		+	<eiffel>
		+	a_container.add_service_with_activator ({LOGGER_SERVICE_S},
		+	agent create_logger_service, False)
		+	</eiffel>
		+
		+	The above line of code registers the logger service with a "[[Services#Delayed Activation\|activator]]", which ensures the service is only created when it's requested. This saves on start up performance degradation as well as not using up memory required to instantiate and run the logger service. It may seem small in the scope of a single, tiny service but every little counts and that count grows with ever services registered.
		+
		+	Services are registered using their service interface type. One reason why the <eiffel>_S</eiffel> suffix is used is for identity. When querying for a service you know instinctively to look for a class name ending <eiffel>_S</eiffel>, which is assignable to an Eiffel variable of the same type.
		+
		+	To actually create the logger service, a factory function is used which has the added advantage of allowing descendants to redefine the default service returned (or return no service at all.)
		+
		+	<eiffel>
		+	feature {NONE} -- Service factories
		+
		+	create_logger_service: LOGGER_SERVICE_S
		+	-- Creates the logger service
		+	do
		+	create {LOGGER_SERVICE}Result.make
		+	end
		+	</eiffel>
		+
		+	== Next Steps ==
		+	With the all the code in place, the logger service is read to be interacted with. In the [[Tutorial: Consuming a Service\|next tutorial]] on [[Services\|services]] we will put the logger service to use in existing functionality in EiffelStudio.
		+
		+	In the [[Tutorial: Creating a Service-Based Tool\|final tutorial]] we'll explorer using [[EiffelStudio Foundataions]] to create a dockable Eiffel tool to display the logged messages.

@@ Line 464: / Line 464: @@
 The factory function, used to create the log ###event list item###:
 feature {NONE} -- Factory
      create_event_list_log_item (a_msg: STRING_32; a_cat: NATURAL_8;
          a_level: INTEGER_8): EVENT_LIST_LOG_ITEM_I
@@ Line 488: / Line 488: @@
 </eiffel>
-The last part to complete the logger event service is implementing <eiffel>clear_log</eiffel>
+The last part to complete the logger event service is implementing <eiffel>clear_log</eiffel>.

← Older revision		Revision as of 21:55, 28 September 2007
Line 414:		Line 414:

	=== Implementing the Service Routines ===		=== Implementing the Service Routines ===
		+	The final stage to complete the implementation of the logger service is to implement the deferred features of <eiffel>LOGGER_SERVICE_S</eiffel>. The logger service is quite compact and only two features require implementing; <eiffel>put_message_with_severity</eiffel> and <eiffel>clear_log</eiffel>.
		+
		+	<eiffel>put_message_with_severity</eiffel> will basically take the information passed in and create an instance of <eiffel>LOGGER_EVENT_LIST_ITEM</eiffel> and push it to the [[Event List Service]], if it's available.
		+
		+	{{Warning\|When working with services it is important to remember that they might not be available for one reason or another, even if they are available when you are debugging. There are multiple reasons for their absence, one being a service did not make the final release because of bugs and time constraints.}}
		+
		+	In order to push and remove ###event list items### to and from the [[Event List Service]], the [[Event List Service]] interface requires a "[[Event List Service#Context Cookie\|Context Cookie]]". A context cookie allows the [[Event List Service]] to track where ###event list items### were added from. Using a [[Event List Service#Context Cookie\|context cookie]] enables tools and services to remove all ###event list items### added by that tool or service in a single step. The benefit of this, apart from simplicity, is the tool or service does not have to manually track what it pushed to the [[Event List Service]] for later removal.
		+
		+	Adding the following code to <eiffel>LOGGER_SERVICE</eiffel> will support <eiffel>put_message_with_severity</eiffel> and <eiffel>clear_log</eiffel> in their endeavors:
		+
		+	<eiffel>
		+	feature {NONE} -- Access
		+
		+	context_cookie: UUID
		+	-- Context cookie for event list service
		+	once
		+	create Result.make_from_string ("E1FFE100-0106-4145-A53F-ED44CE92714D")
		+	end
		+	</eiffel>
		+
		+	<eiffel>put_message_with_severity</eiffel> is not done with. The logger service exposes events, one of which should be published to any subscribers when a message is logged. <eiffel>put_message_with_severity</eiffel> will need to publish the event also.
		+
		+	The full implementation of <eiffel>put_message_with_severity</eiffel> looks like this:
		+
		+	<eiffel>
		+	feature -- Extension
		+
		+	put_message_with_severity (a_msg: STRING_32; a_cat: NATURAL_8; a_level: INTEGER_8)
		+	-- Logs a message specifiying a severity level.
		+	--
		+	-- `a_msg': Message text to log.
		+	-- `a_cat': A optional message category.
		+	-- `a_level': A severity level for the message.
		+	local
		+	l_item: like create_event_list_log_item
		+	do
		+	if is_event_list_service_available then
		+	l_item := create_event_list_log_item (a_msg, a_cat, a_level)
		+	event_list_service.put_event_item (context_cookie, l_item)
		+	end
		+
		+	-- Publish events
		+	message_logged_events.publish ([Current, a_msg, a_cat, a_level])
		+	end
		+	</eiffel>
		+
		+	To support better design, <eiffel>put_message_with_severity</eiffel> should not actually create an instance of <eiffel>LOGGER_EVENT_LIST_ITEM</eiffel> directly. It's possible for another party to take and extend the logger service creating even more specialized log ##event list items###, in which case the descendant logger service should not have to reimplement <eiffel>put_message_with_severity</eiffel> in order to change the type of log ##event list items### pushed to the [[Event List Service]]. To facilitate, instead a factory function will be used to create the log ##event list items###, allowing service extenders to create specialize log ##event list items###.
		+
		+	The factory function, used to create the log ###event list item###:
		+
		+	feature {NONE} -- Factory
		+
		+	<eiffel>
		+	create_event_list_log_item (a_msg: STRING_32; a_cat: NATURAL_8;
		+	a_level: INTEGER_8): EVENT_LIST_LOG_ITEM_I
		+	-- Creates a new event list item for a log message.
		+	--
		+	-- `a_msg': Message text to log.
		+	-- `a_cat': A message category, see {ENVIRONMENT_CATEGORIES}.
		+	-- `a_level': A severity level for the message, See {PRIORITY_LEVELS}.
		+	-- `Result': An event list service item.
		+	require
		+	a_msg_attached: a_msg /= Void
		+	not_a_msg_is_empty: not a_msg.is_empty
		+	a_cat_is_empty_is_valid_category: is_valid_category (a_cat)
		+	a_level_is_valid_severity_level: is_valid_severity_level (a_level)
		+	do
		+	create {EVENT_LIST_LOG_ITEM} Result.make (a_cat, a_msg, a_level)
		+	ensure
		+	result_attached: Result /= Void
		+	result_is_log_item: Result.type = {EVENT_LIST_ITEM_TYPES}.log
		+	end
		+	</eiffel>
		+
		+	The last part to complete the logger event service is implementing <eiffel>clear_log</eiffel>

@@ Line 407: / Line 407: @@
 <eiffel>description</eiffel> is implemented as an attribute and the class invariants taken from <eiffel>EVENT_LIST_ITEM_I.description</eiffel>'s postconditions. The description will serve a the holder of a log message.
-<eiffel>is_valid_data</eiffel> determines if an custom data is valid for the [[Event List Service#Event Items|event list item]] but seeing as not custom data is used by the logger [[Event List Service#Event Items|event item] it's implemented returning always <eiffel>True</eiffel>.
+<eiffel>is_valid_data</eiffel> determines if an custom data is valid for the [[Event List Service#Event Items|event list item]] but seeing as not custom data is used by the logger [[Event List Service#Event Items|event list item]] it's implemented returning always <eiffel>True</eiffel>.
 Finally, <eiffel>LOGGER_EVENT_LIST_ITEM</eiffel>'s creation routine <eiffel>make</eiffel> is used to set the information passed through <eiffel>LOGGER_SERVICE_I.put_message_with_severity_level</eiffel> on the log [[Event List Service#Event Items|event list item]]. The <eiffel>category</eiffel> and <eiffel>priority</eiffel> are members of <eiffel>EVENT_LIST_ITEM</eiffel> and are effective implementations of the deferred parent declarations of <eiffel>EVENT_LIST_ITEM_I</eiffel>