docs/concepts.adoc - tomee - Git at Google

 = Concepts
 :index-group: Unrevised
 :jbake-date: 2018-12-05
 :jbake-type: page
 :jbake-status: published

 OpenEJB was founded on the idea that it would be embedded into
 third-party environments whom would likely already have three things:

 * their one "server" platform with existing clients and protocols
 * their own way to configure their platform
 * existing services like TransactionManager, Security, and Connector

 Thus the focus of OpenEJB was to create an EJB implementation that would
 be easily embeddible, configurable, and customizable.

 Part of achieving that is a drive to be as simple as possible as to not
 over-define and therefore restrict the ability to be embeddible,
 configurable and customizable. Smaller third-party environments could
 easily 'downscale' OpenEJB in their integrations by replacing standard
 components with lighter implementations or removing them all together
 and larger environments could 'upscale' OpenEJB by replacing and adding
 heavier implementations of those standard components likely tailored to
 their systems and infrastructure.

 Container and Server are mentioned in the EJB spec as being separate
 things but are never defined formally. In our world Containers, which
 implement the basic component contract and lifecycle of a bean are not
 coupled to any particular Server, which has the job of providing a
 naming service and providing a way for it's clients to reference and
 invoke components (beans) hosted in Containers. Because Containers have
 no dependence at all only Server, you can run OpenEJB without any Server
 at all in an embedded environment for example without any work or any
 extra overhead. Similarly you can add as many new Server components as
 you want without ever having to modify any Containers.

 There is a very strong pluggability focus in OpenEJB as it was always
 intended to be embedded and customized in other environments. As a
 result all Containers are pluggable, isolated from each other, and no
 one Container is bound to another Container and therefore removing or
 adding a Container has no repercussions on the other Containers in the
 system. TransactionManager, SecurityService and Connector also pluggable
 and are services exposed to Containers. A Container may not be dependent
 on specific implementations of those services. Service Providers define
 what services they are offering (Container, Connector, Security,
 Transaction, etc.) in a file they place in their jar called
 service-jar.xml.

 The service-jar.xml should be placed not in the META-INF but somewhere
 in your package hierarchy (ours is in
 /org/apache/openejb/service-jar.xml) which allows the services in your
 service-jar.xml to be referenced by name (such as
 DefaultStatefulContainer) or more specifically by package and id (such
 as org.apache.openejb#DefaultStatefulContainer).

 The same implementation of a service can be declared several times in a
 service-jar.xml with different ids. This allows for you to setup several
 several different profiles or pre-configured versions of the services
 you provide each with a different name and different set of default
 values for its properties.

 In your openejb.conf file when you declare Containers and Connectors, we
 are actually hooking you up with Service Providers automatically. You
 get what is in the org/apache/openejb/service-jar.xml by default, but
 you are able to point specifically to a specific Service Provider by the
 'provider' attribute on the Container, Connector, TransactionManager,
 SecurityService, etc. elements of the openejb.conf file. When you
 declare a service (Container, Connector, etc.) in your openejb.conf file
 the properties you supply override the properties supplied by the
 Service Provider, thus you only need to specify the properties you'd
 like to change and can have your openejb.conf file as large or as small
 as you would like it. The act of doing this can be thought of as
 essentially instantiating the Service Provider and configuring that
 instance for inclusion in the runtime system.

 For example Container(id=NoTimeoutStatefulContainer,
 provider=DefaultStatefulContainer) could be declared with it's Timeout
 property set to 0 for never, and a
 Container(id=ShortTimeoutStatefulContainer,
 provider=DefaultStatefulContainer) could be declared with it's Timeout
 property set to 15 minutes. Both would be instances of the
 DefaultStatefulContainer Service Provider which is a service of type
 Container.
	= Concepts
	:index-group: Unrevised
	:jbake-date: 2018-12-05
	:jbake-type: page
	:jbake-status: published

	OpenEJB was founded on the idea that it would be embedded into
	third-party environments whom would likely already have three things:

	* their one "server" platform with existing clients and protocols
	* their own way to configure their platform
	* existing services like TransactionManager, Security, and Connector

	Thus the focus of OpenEJB was to create an EJB implementation that would
	be easily embeddible, configurable, and customizable.

	Part of achieving that is a drive to be as simple as possible as to not
	over-define and therefore restrict the ability to be embeddible,
	configurable and customizable. Smaller third-party environments could
	easily 'downscale' OpenEJB in their integrations by replacing standard
	components with lighter implementations or removing them all together
	and larger environments could 'upscale' OpenEJB by replacing and adding
	heavier implementations of those standard components likely tailored to
	their systems and infrastructure.

	Container and Server are mentioned in the EJB spec as being separate
	things but are never defined formally. In our world Containers, which
	implement the basic component contract and lifecycle of a bean are not
	coupled to any particular Server, which has the job of providing a
	naming service and providing a way for it's clients to reference and
	invoke components (beans) hosted in Containers. Because Containers have
	no dependence at all only Server, you can run OpenEJB without any Server
	at all in an embedded environment for example without any work or any
	extra overhead. Similarly you can add as many new Server components as
	you want without ever having to modify any Containers.

	There is a very strong pluggability focus in OpenEJB as it was always
	intended to be embedded and customized in other environments. As a
	result all Containers are pluggable, isolated from each other, and no
	one Container is bound to another Container and therefore removing or
	adding a Container has no repercussions on the other Containers in the
	system. TransactionManager, SecurityService and Connector also pluggable
	and are services exposed to Containers. A Container may not be dependent
	on specific implementations of those services. Service Providers define
	what services they are offering (Container, Connector, Security,
	Transaction, etc.) in a file they place in their jar called
	service-jar.xml.

	The service-jar.xml should be placed not in the META-INF but somewhere
	in your package hierarchy (ours is in
	/org/apache/openejb/service-jar.xml) which allows the services in your
	service-jar.xml to be referenced by name (such as
	DefaultStatefulContainer) or more specifically by package and id (such
	as org.apache.openejb#DefaultStatefulContainer).

	The same implementation of a service can be declared several times in a
	service-jar.xml with different ids. This allows for you to setup several
	several different profiles or pre-configured versions of the services
	you provide each with a different name and different set of default
	values for its properties.

	In your openejb.conf file when you declare Containers and Connectors, we
	are actually hooking you up with Service Providers automatically. You
	get what is in the org/apache/openejb/service-jar.xml by default, but
	you are able to point specifically to a specific Service Provider by the
	'provider' attribute on the Container, Connector, TransactionManager,
	SecurityService, etc. elements of the openejb.conf file. When you
	declare a service (Container, Connector, etc.) in your openejb.conf file
	the properties you supply override the properties supplied by the
	Service Provider, thus you only need to specify the properties you'd
	like to change and can have your openejb.conf file as large or as small
	as you would like it. The act of doing this can be thought of as
	essentially instantiating the Service Provider and configuring that
	instance for inclusion in the runtime system.

	For example Container(id=NoTimeoutStatefulContainer,
	provider=DefaultStatefulContainer) could be declared with it's Timeout
	property set to 0 for never, and a
	Container(id=ShortTimeoutStatefulContainer,
	provider=DefaultStatefulContainer) could be declared with it's Timeout
	property set to 15 minutes. Both would be instances of the
	DefaultStatefulContainer Service Provider which is a service of type
	Container.