Difference between revisions of "Creating a Session (ELUG)"

From Eclipsepedia

Jump to: navigation, search
m (Introduction to the Session Creation)
m
 
(28 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
[[Image:Elug draft icon.png]] '''For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/ '''
 +
 +
----
 
<div style="float:right;border:1px solid #000000;padding:5px">__TOC__
 
<div style="float:right;border:1px solid #000000;padding:5px">__TOC__
 
[[Special:Whatlinkshere/Creating a Session (ELUG)|Related Topics]]</div>
 
[[Special:Whatlinkshere/Creating a Session (ELUG)|Related Topics]]</div>
This section explains how to create EclipseLink sessions.
+
For information on the various types of session available, see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#Session Types|Session Types]].
 
+
For information on the various types of session available, see [[Introduction%20to%20EclipseLink%20Sessions%20(ELUG)#CACJCECI|Session Types]].
+
 
+
 
+
 
+
==Introduction to the Session Creation==
+
  
 
Each EclipseLink session is contained within a sessions configuration (<tt>sessions.xml</tt>) file. You can create a sessions configuration using the Workbench or Java code. We recommend that you use the workbench to create and manage your sessions (see [[#Creating a Sessions Configuration|Creating a Sessions Configuration]]).
 
Each EclipseLink session is contained within a sessions configuration (<tt>sessions.xml</tt>) file. You can create a sessions configuration using the Workbench or Java code. We recommend that you use the workbench to create and manage your sessions (see [[#Creating a Sessions Configuration|Creating a Sessions Configuration]]).
Line 15: Line 12:
 
After you create a session, you must configure its various options (see [[Configuring%20a%20Session%20(ELUG)|Configuring a Session]]). After configuring the session, you can use it in your application to manage persistence (see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)|Acquiring and Using Sessions at Run Time]]).
 
After you create a session, you must configure its various options (see [[Configuring%20a%20Session%20(ELUG)|Configuring a Session]]). After configuring the session, you can use it in your application to manage persistence (see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)|Acquiring and Using Sessions at Run Time]]).
  
==Creating a Sessions Configuration==
 
  
 +
 +
==Creating a Sessions Configuration==
 
The Workbench lets you create session instances and save them in the <tt>sessions.xml</tt> file. These tools represent the <tt>sessions.xml</tt> file as a sessions configuration. Individual session instances are contained within the sessions configuration. You can create multiple sessions configurations, each corresponding to its own uniquely named <tt>sessions.xml</tt> file.
 
The Workbench lets you create session instances and save them in the <tt>sessions.xml</tt> file. These tools represent the <tt>sessions.xml</tt> file as a sessions configuration. Individual session instances are contained within the sessions configuration. You can create multiple sessions configurations, each corresponding to its own uniquely named <tt>sessions.xml</tt> file.
  
Line 23: Line 21:
 
Workbench displays sessions configurations and their contents in the Navigator window. When you select a session configuration, its attributes are displayed in the Editor window.
 
Workbench displays sessions configurations and their contents in the Navigator window. When you select a session configuration, its attributes are displayed in the Editor window.
  
[[#Figure 84-1|Sessions Configurations in Navigator Window]] calls out the following user interface elements:
+
The [[#Figure 84-1|Sessions Configurations in Navigator Window]] figure calls out the following user interface elements:
 
+
 
# Sessions Configuration
 
# Sessions Configuration
 
# Database Session
 
# Database Session
Line 38: Line 35:
  
 
[[Image:navpane.gif|Sessions Configurations in Navigator Window]]<br><br>
 
[[Image:navpane.gif|Sessions Configurations in Navigator Window]]<br><br>
 +
  
 
===How to Create a Sessions Configuration Using Workbench===
 
===How to Create a Sessions Configuration Using Workbench===
 +
To create an EclipseLink sessions configuration (<tt>sessions.xml</tt> file), use this procedure:
 +
 +
# Click '''New''' [[Image:creatbtn.gif|New Project button]] on the toolbar and select '''Sessions Configuration'''.<br>You can also create a new sessions configuration by selecting '''File > New > Session Configuration''' from the menu, or by clicking '''Create New Sessions Configuration''' [[Image:crnewses.gif|New Sessions Configuration button]] in the standard toolbar.
 +
# The new sessions configuration element appears in the Navigator window; the Sessions Configuration property sheet appears in the Editor window.<br>Enter data in each field on the Sessions Configuration property sheet, as [[#Configuring a Sessions Configuration|Configuring a Sessions Configuration]] describes.
  
To create a EclipseLink sessions configuration (<tt>sessions.xml</tt> file), use this procedure:
 
  
# [[Image:creatbtn.gif|New Project button]] Click '''New''' on the toolbar and select '''Sessions Configuration'''.<br>[[Image:crnewses.gif|New Sessions Configuration button]]<br> You can also create a new sessions configuration by selecting '''File > New > Session Configuration''' from the menu, or by clicking '''Create New Sessions Configuration''' in the standard toolbar.
 
# The new sessions configuration element appears in the Navigator window; the Sessions Configuration property sheet appears in the Editor window. Enter data in each field on the Sessions Configuration property sheet as [[#Configuring a Sessions Configuration|Configuring a Sessions Configuration]] describes.Enter data in each field on the Sessions Configuration property sheet as [[#CConfiguring a Sessions Configuration|onfiguring a Sessions Configuration]] describes.
 
  
 
==Configuring a Sessions Configuration==
 
==Configuring a Sessions Configuration==
 
 
Each EclipseLink sessions configuration (<tt>sessions.xml</tt> file) can contain multiple sessions and session brokers. In addition, you can specify a classpath for each sessions configuration that applies to all the sessions it contains.
 
Each EclipseLink sessions configuration (<tt>sessions.xml</tt> file) can contain multiple sessions and session brokers. In addition, you can specify a classpath for each sessions configuration that applies to all the sessions it contains.
 
  
  
 
===How to Configure a Sessions Configuration Using Workbench===
 
===How to Configure a Sessions Configuration Using Workbench===
 
 
To configure a session configuration, use this procedure:
 
To configure a session configuration, use this procedure:
 +
# Select the session configuration in the '''Navigator'''. Its properties appear in the Editor.<br><span id="Figure 84-2"></span>''''' Sessions Configuration Property Sheet'''''<br>[[Image:sescfg.gif|Sessions Configuration Property Sheet]]<br><br>
 +
# Enter data in each field on the Sessions Configuration property sheet.
  
# Select the session configuration in the '''Navigator'''. Its properties appear in the Editor.'''''Figure 84-2 Sessions Configuration Property Sheet'''''[[Image:sescfg.gif|Description of Figure 84-2 follows]]<br>[img_text/sescfg Description of "Figure 84-2 Sessions Configuration Property Sheet"]<br><br>
 
# Enter data in each field on the [topicid:scproject.location Sessions Configuration property sheet.]
 
  
 
Use the following information to enter data in each field of the Sessions configuration property sheet:
 
Use the following information to enter data in each field of the Sessions configuration property sheet:
 
 
 
 
{| class="HRuleInformal" dir="ltr" title="This table identifies each field on the Session Configuration propery sheet." summary="This table identifies each field on the Session Configuration propery sheet." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 
{| class="HRuleInformal" dir="ltr" title="This table identifies each field on the Session Configuration propery sheet." summary="This table identifies each field on the Session Configuration propery sheet." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
Line 83: Line 76:
 
* To add a session, click '''Add Session'''.
 
* To add a session, click '''Add Session'''.
 
* To remove a session, select the session and click '''Remove'''.
 
* To remove a session, select the session and click '''Remove'''.
* To rename a session, select the session and click '''Rename'''.For more information on creating sessions using Workbench, seen the following:
+
* To rename a session, select the session and click '''Rename'''.
** [[#Creating a Server Session]]
+
 
** [[#Creating Session Broker and Client Sessions]]
+
For more information on creating sessions using Workbench, see the following:
** [[#Creating Database Sessions]]
+
** [[#Creating a Server Session|Creating a Server Session]]
 +
** [[#Creating Session Broker and Client Sessions|Creating Session Broker and Client Sessions]]
 +
** [[#Creating Database Sessions|Creating Database Sessions]]
 
|}
 
|}
  
<br>
 
  
'''See Also'''
+
See Also:
: [[#Configuring a Sessions Configuration]]
+
: [[#Configuring a Sessions Configuration|Configuring a Sessions Configuration]]
 +
 
 +
 
  
 
==Creating a Server Session==
 
==Creating a Server Session==
 
+
We recommend that you create server sessions using the Workbench (see [[#How to Create a Server Session Using Workbench|How to Create a Server Session Using Workbench]]).
We recommend that you create server sessions using the Workbench (see [[#How to Create a Server Session Using Workbench]]).
+
  
 
After you create a server session, you create a client session by acquiring it from the server session (see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)|Acquiring a Client Session]]).
 
After you create a server session, you create a client session by acquiring it from the server session (see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)|Acquiring a Client Session]]).
 
  
  
 
===How to Create a Server Session Using Workbench===
 
===How to Create a Server Session Using Workbench===
 
+
Before you create a server session, you must first create a sessions configuration (see [[#Creating a Sessions Configuration|Creating a Sessions Configuration]]).
Before you create a server session, you must first create a sessions configuration (see [[#Creating a Sessions Configuration]]).
+
  
 
To create a new EclipseLink server session, use this procedure:
 
To create a new EclipseLink server session, use this procedure:
 
 
# Select the sessions configuration in the '''Navigator''' window in which you want to create a session.
 
# Select the sessions configuration in the '''Navigator''' window in which you want to create a session.
# [[Image:sessbtn.gif|Add Session button]]<br> Click '''Add Session''' on the toolbar. The Create New Session dialog box appears.You can also create a new server session by right-clicking the sessions configuration in the '''Navigator''' and selecting '''New > Session''' from the context menu, or by clicking '''Add Session''' on the Sessions Configuration property sheet.'''''Figure 84-3 Create New Session Dialog Box, Server Session Option'''''<br>[[Image:newsess.gif|Description of Figure 84-3 follows]]<br>[img_text/newsess Description of "Figure 84-3 Create New Session Dialog Box, Server Session Option"]<br><br>
+
# Click '''Add Session''' [[Image:sessbtn.gif|Add Session button]] on the toolbar. The Create New Session dialog box appears.<br>You can also create a new server session by right-clicking the sessions configuration in the '''Navigator''' and selecting '''New > Session''' from the context menu, or by clicking '''Add Session''' on the Sessions Configuration property sheet.<br><span id="Figure 84-3"></span>''''' Create New Session Dialog Box, Server Session Option'''''<br>[[Image:newsess.gif|Create New Session Dialog Box, Server Session Option]]<br><br>
 
# Enter data in each field on the Create New Session dialog box.
 
# Enter data in each field on the Create New Session dialog box.
 
Use the following information to enter data in each field of the dialog box:
 
  
  
 +
Use the following information to enter data in each field of the dialog box:
  
 
{| class="HRuleInformal" dir="ltr" title="This table defines each field on the Create New Session dialog." summary="This table defines each field on the Create New Session dialog." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 
{| class="HRuleInformal" dir="ltr" title="This table defines each field on the Create New Session dialog." summary="This table defines each field on the Create New Session dialog." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
Line 126: Line 117:
 
| id="r3c1-t3" headers="r1c1-t3" align="left" | '''Use Server Platform'''
 
| id="r3c1-t3" headers="r1c1-t3" align="left" | '''Use Server Platform'''
 
| headers="r3c1-t3 r1c2-t3" align="left" |
 
| headers="r3c1-t3 r1c2-t3" align="left" |
Check this field if you intend to deploy your application to a Java EE application server. If you check this field, you must configure the target application server by selecting a '''Platform'''.
+
Check this field if you intend to deploy your application to a Java EE application server.  
 +
 
 +
If you check this field, you must configure the target application server by selecting a '''Platform'''.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t3" headers="r1c1-t3" align="left" | '''Platform'''
 
| id="r4c1-t3" headers="r1c1-t3" align="left" | '''Platform'''
 
| headers="r4c1-t3 r1c2-t3" align="left" |
 
| headers="r4c1-t3 r1c2-t3" align="left" |
This option is only available if you check '''Use Server Platform'''. Select the Java EE application server to which you will deploy your application.EclipseLink supports the following Java EE application servers:
+
This option is only available if you check '''Use Server Platform'''.  
* OC4J 11.1.1
+
 
* OC4J 10.1.3
+
Select the Java EE application server to which you will deploy your application.
* OC4J 9.0.4
+
 
* OC4J 9.0.3
+
EclipseLink supports the following Java EE application servers:
* SunAS 9.0
+
* WebLogic 10.n
* WebLogic 10.0
+
 
* WebLogic 9.0
 
* WebLogic 9.0
 +
* OC4J 10.1.3.n
 +
* SunAS 9.0
 
* WebSphere 6.1
 
* WebSphere 6.1
* WebSphere 5.1
 
 
* JBoss
 
* JBoss
* CustomThe server platform you select is the default server platform for all sessions you create in this sessions configuration. At the session level, you can override this selection or specify a custom server platform class (see [Configuring%20a%20Session%20(ELUG)|Configuring the Server Platform]).
+
* Custom
 +
The server platform you select is the default server platform for all sessions you create in this sessions configuration. At the session level, you can override this selection or specify a [[Configuring%20a%20Session%20(ELUG)#Configuring the Server Platform|custom server platform class]].
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t3" headers="r1c1-t3" align="left" | '''Select Data Source'''
 
| id="r5c1-t3" headers="r1c1-t3" align="left" | '''Select Data Source'''
Line 148: Line 142:
 
* '''Database''' to create a session for a relational project.
 
* '''Database''' to create a session for a relational project.
 
* '''EIS''' to create a session for an EIS project.
 
* '''EIS''' to create a session for an EIS project.
* '''XML''' to create a session for an XML project[#sthref2802 <sup>Foot 1 </sup>].See [[Introduction%20to%20Projects#BABEHBCI|EclipseLink Project Types]] for more information.
+
* '''XML''' to create a session for an XML project <sup> 1 </sup>.  
 +
 
 +
See [[Introduction%20to%20Projects (ELUG)#EclipseLink Project Types|EclipseLink Project Types]] for more information.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r6c1-t3" headers="r1c1-t3" align="left" | '''Select Session'''
 
| id="r6c1-t3" headers="r1c1-t3" align="left" | '''Select Session'''
Line 154: Line 150:
 
|}
 
|}
  
<br><sup>Footnote 1 </sup>You cannot create a server session for an XML project.<br>
+
<br><sup>1 </sup>You cannot create a server session for an XML project.<br>
  
 
===How to Create a Server Session Using Java===
 
===How to Create a Server Session Using Java===
 
 
You can create a server session in Java code using a project. You can create a project in Java code, or read a project from a <tt>project.xml</tt> file.
 
You can create a server session in Java code using a project. You can create a project in Java code, or read a project from a <tt>project.xml</tt> file.
  
[#CHECFDBD Example 84-1] illustrates creating an instance (called <tt>serverSession</tt>) of a <tt>Server</tt> class using a <tt>Project</tt> class.
+
This example illustrates creating an instance (called <tt>serverSession</tt>) of a <tt>Server</tt> class using a <tt>Project</tt> class.
  
  
 
+
<span id="Example 84-1"></span>
'''''Example 84-1 Creating a Server Session from a Project Class'''''
+
''''' Creating a Server Session from a Project Class'''''
 
+
<source lang="java">
+
 
  Project myProject = new Project();
 
  Project myProject = new Project();
 
  Server serverSession = myProject.createServerSession();
 
  Server serverSession = myProject.createServerSession();
 +
</source>
  
 +
This example illustrates creating an instance (called <tt>serverSession</tt>) of a <tt>Server</tt> class using a <tt>Project</tt> read in from a <tt>project.xml</tt> file.
  
 
+
<span id="Example 84-2"></span>
[#CHEJIBEE Example 84-2] illustrates creating an instance (called <tt>serverSession</tt>) of a <tt>Server</tt> class using a <tt>Project</tt> read in from a <tt>project.xml</tt> file.
+
''''' Creating a Server Session from a project.xml File Project'''''
 
+
<source lang="java">
 
+
 
+
'''''Example 84-2 Creating a Server Session from a project.xml File Project'''''
+
 
+
+
 
  Project myProject = XMLProjectReader.read("myproject.xml");
 
  Project myProject = XMLProjectReader.read("myproject.xml");
 
  Server serverSession = myProject.createServerSession();
 
  Server serverSession = myProject.createServerSession();
 +
</source>
  
 +
This example illustrates creating a server session with a specified write connection pool minimum and maximum size (when using EclipseLink internal connection pooling). The default write connection pool minimum size is 5 and maximum size is 10.
  
  
[#CHEGJAFB Example 84-3] illustrates creating a server session with a specified write connection pool minimum and maximum size (when using EclipseLink internal connection pooling). The default write connection pool minimum size is 5 and maximum size is 10.
+
<span id="Example 84-3"></span>
 
+
''''' Creating a Server Session with Custom Write Connection Pool Size'''''
 
+
<source lang="java">
 
+
'''''Example 84-3 Creating a Server Session with Custom Write Connection Pool Size'''''
+
 
+
+
 
  XMLProjectReader.read("myproject.xml");
 
  XMLProjectReader.read("myproject.xml");
 
  Server serverSession = myProject.createServerSession(32, 32);
 
  Server serverSession = myProject.createServerSession(32, 32);
 +
</source>
  
==Creating Session Broker and Client Sessions==
 
  
 +
==Creating Session Broker and Client Sessions==
 
A session broker may contain both server sessions and database sessions. We recommend that you use the session broker with server sessions because server sessions are the most scalable session type.
 
A session broker may contain both server sessions and database sessions. We recommend that you use the session broker with server sessions because server sessions are the most scalable session type.
  
We recommend that you create server sessions using the Workbench (see [[#How to Create a Session Broker and Client Sessions Using Workbench]]).
+
We recommend that you create server sessions [[#How to Create a Session Broker and Client Sessions Using Workbench|using the Workbench]]).
 
+
After you create and configure a session broker with server sessions, you can acquire a client session from the session broker at run time to provide a dedicated connection to all the data sources managed by the session broker for each client. For more information, see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)|Acquiring a Client Session]].
+
  
 +
After you create and configure a session broker with server sessions, you can acquire a client session from the session broker at run time to provide a dedicated connection to all the data sources managed by the session broker for each client. For more information, see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)#Acquiring a Client Session|Acquiring a Client Session]].
  
  
 
===How to Create a Session Broker and Client Sessions Using Workbench===
 
===How to Create a Session Broker and Client Sessions Using Workbench===
 
+
Before you create a session broker session, you must first create a sessions configuration (see [[#Creating a Sessions Configuration|Creating a Sessions Configuration]]) and one or more server sessions (see [[#Creating a Server Session|Creating a Server Session]]), or one or more database sessions (see [[#Creating Database Sessions|Creating Database Sessions]]).
Before you create a session broker session, you must first create a sessions configuration (see [#CHECFEIH Creating a Sessions Configuration]) and one or more server sessions ( [[#Creating a Server Session]]), or one or more database sessions ( [[#Creating Database Sessions]]).
+
  
 
To create a new EclipseLink session broker, use this procedure:
 
To create a new EclipseLink session broker, use this procedure:
 
 
# Select the sessions configuration in the '''Navigator''' window in which you want to create a session broker.
 
# Select the sessions configuration in the '''Navigator''' window in which you want to create a session broker.
# [[Image:sesbkbtn.gif|Add Session Broker button]]<br> Click '''Add Session Broker''' on the toolbar. The Create New Session Broker dialog box appears.You can also create a new session broker by right-clicking the sessions configuration in the '''Navigator''' window and selecting '''Add Session Broker''' from the context menu or by clicking '''Add Session Broker''' on the Sessions Configuration property sheet.'''''Figure 84-4 Create New Session Broker Dialog Box'''''[[Image:newsesb.gif|Description of Figure 84-4 follows]]<br>[img_text/newsesb Description of "Figure 84-4 Create New Session Broker Dialog Box"]<br><br>
+
# Click '''Add Session Broker''' [[Image:sesbkbtn.gif|Add Session Broker button]] on the toolbar. The Create New Session Broker dialog box appears.<br>You can also create a new session broker by right-clicking the sessions configuration in the '''Navigator''' window and selecting '''Add Session Broker''' from the context menu or by clicking '''Add Session Broker''' on the Sessions Configuration property sheet.<span id="Figure 84-4"></span><br>''''' Create New Session Broker Dialog Box'''''<br>[[Image:newsesb.gif|Create New Session Broker Dialog Box]]<br><br>
 
# Enter data in each field on the New Session Broker dialog box.
 
# Enter data in each field on the New Session Broker dialog box.
  
 
Use the following information to enter data in each field of the dialog box:
 
Use the following information to enter data in each field of the dialog box:
 
 
 
 
{| class="HRuleInformal" dir="ltr" title="This table defines each field on the New Session Broker dialog." summary="This table defines each field on the New Session Broker dialog." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 
{| class="HRuleInformal" dir="ltr" title="This table defines each field on the New Session Broker dialog." summary="This table defines each field on the New Session Broker dialog." width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
 
|- align="left" valign="top"
 
|- align="left" valign="top"
Line 228: Line 212:
 
| id="r3c1-t4" headers="r1c1-t4" align="left" | '''Use Server Platform'''
 
| id="r3c1-t4" headers="r1c1-t4" align="left" | '''Use Server Platform'''
 
| headers="r3c1-t4 r1c2-t4" align="left" |
 
| headers="r3c1-t4 r1c2-t4" align="left" |
Check this field if you intend to deploy your application to a Java EE application server. If you check this field, you must configure the target application server by selecting a '''Platform'''.
+
Check this field if you intend to deploy your application to a Java EE application server.  
 +
 
 +
If you check this field, you must configure the target application server by selecting a '''Platform'''.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t4" headers="r1c1-t4" align="left" | '''Platform'''
 
| id="r4c1-t4" headers="r1c1-t4" align="left" | '''Platform'''
 
| headers="r4c1-t4 r1c2-t4" align="left" |
 
| headers="r4c1-t4 r1c2-t4" align="left" |
This option is available only if you check '''Use Server Platform'''. Select the Java EE application server to which you will deploy your application.EclipseLink supports the following Java EE application servers:
+
This option is available only if you check '''Use Server Platform'''.  
* OC4J 11.1.1
+
 
* OC4J 10.1.3
+
Select the Java EE application server to which you will deploy your application.
* OC4J 9.0.4
+
 
* OC4J 9.0.3
+
EclipseLink supports the following Java EE application servers:
* SunAS 9.0
+
* WebLogic 10.n
* WebLogic 10.0
+
 
* WebLogic 9.0
 
* WebLogic 9.0
 +
* OC4J 10.1.3.n
 +
* SunAS 9.0
 
* WebSphere 6.1
 
* WebSphere 6.1
* WebSphere 5.1
 
 
* JBoss
 
* JBoss
* CustomThe server platform you select is the default server platform for all sessions you create in this sessions configuration. At the session level, you can override this selection or specify a custom server platform class (see [Configuring%20a%20Session%20(ELUG)|Configuring the Server Platform]).
+
* Custom
 +
The server platform you select is the default server platform for all sessions you create in this sessions configuration. At the session level, you can override this selection or specify a [[Configuring%20a%20Session%20(ELUG)#Configuring the Server Platform|custom server platform class]].
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t4" headers="r1c1-t4" align="left" | '''Select the sessions to Manage'''
 
| id="r5c1-t4" headers="r1c1-t4" align="left" | '''Select the sessions to Manage'''
 
| headers="r5c1-t4 r1c2-t4" align="left" |
 
| headers="r5c1-t4 r1c2-t4" align="left" |
Select sessions to be managed by this new session broker (from the list of available sessions) and click '''OK'''. '''Note'''<nowiki>: This field appears only if the configuration contains valid sessions.</nowiki>
+
Select sessions to be managed by this new session broker (from the list of available sessions) and click '''OK'''.  
 +
 
 +
'''Note'''<nowiki>: This field appears only if the configuration contains valid sessions.</nowiki>
 
|}
 
|}
  
<br>
 
  
Continue with [[Configuring%20a%20Session%20(ELUG)|Configuring a Session]].
+
Continue with [[Configuring%20a%20Session%20(ELUG)#Configuring a Session|Configuring a Session]].
 
+
'''See Also'''
+
  
: [[#Creating Session Broker and Client Sessions]]
+
See Also:
 +
: [[#Creating Session Broker and Client Sessions|Creating Session Broker and Client Sessions]]
 
: [[Configuring%20a%20Session%20(ELUG)|Configuring a Session]]
 
: [[Configuring%20a%20Session%20(ELUG)|Configuring a Session]]
 
 
  
 
===How to Create a Session Broker and Client Sessions Using Java===
 
===How to Create a Session Broker and Client Sessions Using Java===
 
+
This example illustrates how you can create a session broker in Java code by instantiating a <tt>SessionBroker</tt> and registering the brokered sessions with it.
[#CHEJBDBH Example 84-4] illustrates how you can create a session broker in Java code by instantiating a <tt>SessionBroker</tt> and registering the brokered sessions with it.
+
  
 
Because the session broker references other sessions, configure these sessions before instantiating the session broker. Add all required descriptors to the session, but do not initialize the descriptors or log the sessions. The session broker manages these issues when you instantiate it.
 
Because the session broker references other sessions, configure these sessions before instantiating the session broker. Add all required descriptors to the session, but do not initialize the descriptors or log the sessions. The session broker manages these issues when you instantiate it.
  
  
 
+
<span id="Example 84-4"></span>
'''''Example 84-4 Creating a Session Broker'''''
+
''''' Creating a Session Broker'''''
 
+
<source lang="java">
+
 
  Project databaseProject = new MyDatabaseProject();
 
  Project databaseProject = new MyDatabaseProject();
 
  Server databaseSession = databaseProject.createServerSession();
 
  Server databaseSession = databaseProject.createServerSession();
Line 283: Line 266:
 
   
 
   
 
  sessionBroker.login();
 
  sessionBroker.login();
 +
</source>
  
==Creating Database Sessions==
 
  
 +
==Creating Database Sessions==
 
We recommend that you create database sessions using the Workbench (see [[#How to Create Database Sessions Using Workbench|How to Create Database Sessions Using Workbench]]).
 
We recommend that you create database sessions using the Workbench (see [[#How to Create Database Sessions Using Workbench|How to Create Database Sessions Using Workbench]]).
  
 
After you create a database session, you can acquire and use it at run time. For more information on acquiring a database session, see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)|Acquiring a Session from the Session Manager]].
 
After you create a database session, you can acquire and use it at run time. For more information on acquiring a database session, see [[Acquiring%20and%20Using%20Sessions%20at%20Run%20Time%20(ELUG)|Acquiring a Session from the Session Manager]].
 
  
  
 
===How to Create Database Sessions Using Workbench===
 
===How to Create Database Sessions Using Workbench===
 
+
Before you create a database session, you must first [[#Creating a Sessions Configuration|create a sessions configuration]].
Before you create a database session, you must first create a sessions configuration (see [[#Creating a Sessions Configuration|Creating a Sessions Configuration]]).
+
  
 
To create a new EclipseLink database session, use this procedure:
 
To create a new EclipseLink database session, use this procedure:
 
 
# Select the session configuration in the '''Navigator''' window in which you want to create a session.
 
# Select the session configuration in the '''Navigator''' window in which you want to create a session.
# [[Image:creatbtn.gif|Add Session button.]] Click '''Add Session''' on the toolbar. The Create New Session dialog box appears.You can also create a new configuration by right-clicking the sessions configuration in the '''Navigator''' window and selecting '''New > Session''' from the context menu.<br><span id="Figure 84-5"></span>''''' Create New Session Dialog Box, Database Session Option'''''<br>[[Image:newsesd.gif|Create New Session Dialog Box, Database Session Option]]<br><br>
+
# Click '''Add Session''' [[Image:creatbtn.gif|Add Session button.]] on the toolbar. The Create New Session dialog box appears.<br>You can also create a new configuration by right-clicking the sessions configuration in the '''Navigator''' window and selecting '''New > Session''' from the context menu.<br><span id="Figure 84-5"></span>''''' Create New Session Dialog Box, Database Session Option'''''<br>[[Image:newsesd.gif|Create New Session Dialog Box, Database Session Option]]<br><br>
 
# Complete each field on the Create New Session dialog box.
 
# Complete each field on the Create New Session dialog box.
  
Line 313: Line 294:
 
| id="r3c1-t5" headers="r1c1-t5" align="left" | '''Use Server Platform'''
 
| id="r3c1-t5" headers="r1c1-t5" align="left" | '''Use Server Platform'''
 
| headers="r3c1-t5 r1c2-t5" align="left" |
 
| headers="r3c1-t5 r1c2-t5" align="left" |
Check this field if you intend to deploy your application to a Java EE application server. If you check this field, you must configure the target application server by selecting a '''Platform'''.
+
Check this field if you intend to deploy your application to a Java EE application server.  
 +
 
 +
If you check this field, you must configure the target application server by selecting a '''Platform'''.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r4c1-t5" headers="r1c1-t5" align="left" | '''Platform'''
 
| id="r4c1-t5" headers="r1c1-t5" align="left" | '''Platform'''
 
| headers="r4c1-t5 r1c2-t5" align="left" |
 
| headers="r4c1-t5 r1c2-t5" align="left" |
This option is available only if you check '''Use Server Platform'''. Select the Java EE application server to which you will deploy your application.EclipseLink supports the following Java EE application servers:
+
This option is available only if you check '''Use Server Platform'''.  
* OC4J 11.1.1
+
 
* OC4J 10.1.3
+
Select the Java EE application server to which you will deploy your application.
* OC4J 9.0.4
+
 
* OC4J 9.0.3
+
EclipseLink supports the following Java EE application servers:
* SunAS 9.0
+
* WebLogic 10.n
* WebLogic 10.0
+
 
* WebLogic 9.0
 
* WebLogic 9.0
 +
* OC4J 10.1.3.n
 +
* SunAS 9.0
 
* WebSphere 6.1
 
* WebSphere 6.1
* WebSphere 5.1
 
 
* JBoss
 
* JBoss
* CustomThe server platform you select is the default server platform for all sessions you create in this sessions configuration. At the session level, you can override this selection or specify a custom server platform class (see [[Configuring%20a%20Session%20(ELUG)#Configuring the Server Platform|Configuring the Server Platform]]).
+
* Custom
 +
The server platform you select is the default server platform for all sessions you create in this sessions configuration. At the session level, you can override this selection or specify a [[Configuring%20a%20Session%20(ELUG)#Configuring the Server Platform|custom server platform class]].
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r5c1-t5" headers="r1c1-t5" align="left" | '''Select Data Source'''
 
| id="r5c1-t5" headers="r1c1-t5" align="left" | '''Select Data Source'''
Line 335: Line 319:
 
* '''Database''' to create a session for a relational project.
 
* '''Database''' to create a session for a relational project.
 
* '''EIS''' to create a session for an EIS project.
 
* '''EIS''' to create a session for an EIS project.
* '''XML''' to create a session for an XML project.See [[Introduction%20to%20Projects#EclipseLink Project Types|EclipseLink Project Types]] for more information.
+
* '''XML''' to create a session for an XML project.  
 +
See [[Introduction%20to%20Projects (ELUG)#EclipseLink Project Types|EclipseLink Project Types]] for more information.
 
|- align="left" valign="top"
 
|- align="left" valign="top"
 
| id="r6c1-t5" headers="r1c1-t5" align="left" | '''Select Session'''
 
| id="r6c1-t5" headers="r1c1-t5" align="left" | '''Select Session'''
Line 348: Line 333:
  
 
Continue with [[Configuring%20a%20Session%20(ELUG)#Configuring a Session|Configuring a Session]].
 
Continue with [[Configuring%20a%20Session%20(ELUG)#Configuring a Session|Configuring a Session]].
 
 
  
 
===How to Create Database Sessions Using Java===
 
===How to Create Database Sessions Using Java===
 
 
You can create an instance of the <tt>DatabaseSession</tt> class in Java code using a <tt>Project</tt>. You can create a project in Java code or read a project from a <tt>project.xml</tt> file.
 
You can create an instance of the <tt>DatabaseSession</tt> class in Java code using a <tt>Project</tt>. You can create a project in Java code or read a project from a <tt>project.xml</tt> file.
  
Line 360: Line 342:
 
<span id="Example 84-5"></span>
 
<span id="Example 84-5"></span>
 
''''' Creating a Database Session from a Project Class'''''
 
''''' Creating a Database Session from a Project Class'''''
 +
<source lang="java">
 
  Project myProject = new Project();
 
  Project myProject = new Project();
 
  DatabaseSession databaseSession = myProject.createDatabaseSession();
 
  DatabaseSession databaseSession = myProject.createDatabaseSession();
 
+
</source>
 
+
  
 
This example illustrates creating a <tt>DatabaseSession</tt> using a <tt>Project</tt> read in from a <tt>project.xml</tt> file.
 
This example illustrates creating a <tt>DatabaseSession</tt> using a <tt>Project</tt> read in from a <tt>project.xml</tt> file.
Line 370: Line 352:
 
<span id="Example 84-6"></span>
 
<span id="Example 84-6"></span>
 
''''' Creating a Database Session from a project.xml File Project'''''
 
''''' Creating a Database Session from a project.xml File Project'''''
 
+
<source lang="java">
 
  Project myProject = XMLProjectReader.read("myproject.xml");
 
  Project myProject = XMLProjectReader.read("myproject.xml");
 
  DatabaseSession databaseSession = myProject.createDatabaseSession();
 
  DatabaseSession databaseSession = myProject.createDatabaseSession();
 +
</source>
 +
  
 
==Creating Remote Sessions==
 
==Creating Remote Sessions==
 
 
Remote sessions are acquired through a remote connection to their server-side session. Remote sessions are acquired through Java code on the remote client. The server-side session must also be registered with an <tt>org.eclipse.persistence.remote.ejb.RemoteSessionController</tt> and accessible from the RMI naming service.
 
Remote sessions are acquired through a remote connection to their server-side session. Remote sessions are acquired through Java code on the remote client. The server-side session must also be registered with an <tt>org.eclipse.persistence.remote.ejb.RemoteSessionController</tt> and accessible from the RMI naming service.
  
You create remote sessions entirely in Java code (see [#How to Create Remote Sessions Using Java|How to Create Remote Sessions Using Java]).
+
You create remote sessions entirely in [[#How to Create Remote Sessions Using Java|Java code]].
  
  
  
 
===How to Create Remote Sessions Using Java===
 
===How to Create Remote Sessions Using Java===
 
+
The [[#Example 84-7|Server Creating RMIRemoteSessionController for Client]] and [[#Example 84-8|Client Acquiring RMIRemoteSessionController from Server]] examples demonstrate how to create a remote EclipseLink session on a client that communicates with a remote session controller on a server that uses RMI. After creating the connection, the client application uses the remote session as it does with any other EclipseLink session.
[[#Example 84-7|Server Creating RMIRemoteSessionController for Client]] and [[#Example 84-8|Client Acquiring RMIRemoteSessionController from Server]] demonstrate how to create a remote EclipseLink session on a client that communicates with a remote session controller on a server that uses RMI. After creating the connection, the client application uses the remote session as it does with any other EclipseLink session.
+
 
+
  
  
 
====Server====
 
====Server====
 +
The [[#Example 84-7|Server Creating RMIRemoteSessionController for Client]] example shows the code you add to your application's RMI service (<tt>MyRMIServerManagerImpl</tt>) to create and return an instance of an <tt>RMIRemoteSessionController</tt> to the client. The controller sits between the remote client and the local EclipseLink session.
  
[[#Example 84-7|Server Creating RMIRemoteSessionController for Client]] shows the code you add to your application's RMI service (<tt>MyRMIServerManagerImpl</tt>) to create and return an instance of an <tt>RMIRemoteSessionController</tt> to the client. The controller sits between the remote client and the local EclipseLink session.
+
The <tt>RMIRemoteSessionController</tt> you create on the server is based on an EclipseLink server session. You create and configure this server session as described in [[#Creating a Server Session|Creating a Server Session]] and [[Configuring%20Server%20Sessions%20(ELUG)|Configuring Server Sessions]].
 
+
The <tt>RMIRemoteSessionController</tt> you create on the server is based on a EclipseLink server session. You create and configure this server session as described in [[#Creating a Server Session|Creating a Server Session]] and [[Configuring%20Server%20Sessions%20(ELUG)|Configuring Server Sessions]].
+
  
  
 
<span id="Example 84-7"></span>
 
<span id="Example 84-7"></span>
 
''''' Server Creating RMIRemoteSessionController for Client'''''
 
''''' Server Creating RMIRemoteSessionController for Client'''''
 +
<source lang="java">
 
  RMIRemoteSessionController controller = null;
 
  RMIRemoteSessionController controller = null;
 
  try {
 
  try {
     '''// Create instance of RMIRemoteSessionControllerDispatcher which implements'''
+
     // Create instance of RMIRemoteSessionControllerDispatcher which implements
     '''// RMIRemoteSessionController. The constructor takes a EclipseLink session as a parameter'''
+
     // RMIRemoteSessionController. The constructor takes an EclipseLink session as a parameter
 
     controller = new RMIRemoteSessionControllerDispatcher (localEclipseLinkSession);
 
     controller = new RMIRemoteSessionControllerDispatcher (localEclipseLinkSession);
 
  }  
 
  }  
Line 408: Line 389:
 
  return controller;
 
  return controller;
  
 
+
</source>
 
+
 
====Client====
 
====Client====
 
 
The client-side code gets a reference to the application's RMI service (in this example it is called <tt>MyRMIServerManager</tt>) and uses this code to get the <tt>RMIRemoteSessionController</tt> running on the server. The reference to the session controller is then used to create the <tt>RMIConnection</tt> from which it acquires a remote session.
 
The client-side code gets a reference to the application's RMI service (in this example it is called <tt>MyRMIServerManager</tt>) and uses this code to get the <tt>RMIRemoteSessionController</tt> running on the server. The reference to the session controller is then used to create the <tt>RMIConnection</tt> from which it acquires a remote session.
  
Line 417: Line 396:
 
<span id="Example 84-8"></span>
 
<span id="Example 84-8"></span>
 
''''' Client Acquiring RMIRemoteSessionController from Server'''''
 
''''' Client Acquiring RMIRemoteSessionController from Server'''''
 +
<source lang="java">
 
  MyRMIServerManager serverManager = null;
 
  MyRMIServerManager serverManager = null;
'''// Set the client security manager'''
 
 
   
 
   
 +
// Set the client security manager
 
  try {
 
  try {
 
     System.setSecurityManager(new MyRMISecurityManager());
 
     System.setSecurityManager(new MyRMISecurityManager());
Line 426: Line 406:
 
     System.out.println("Security violation " + exception.toString());
 
     System.out.println("Security violation " + exception.toString());
 
  }
 
  }
  '''// Get the remote factory object from the Registry'''
+
  // Get the remote factory object from the Registry
 
  try {
 
  try {
 
     serverManager = (MyRMIServerManager) Naming.lookup("SERVER-MANAGER");
 
     serverManager = (MyRMIServerManager) Naming.lookup("SERVER-MANAGER");
Line 433: Line 413:
 
     System.out.println("Lookup failed " + exception.toString());
 
     System.out.println("Lookup failed " + exception.toString());
 
  }
 
  }
  '''// Start RMIRemoteSession on the server and create an RMIConnection'''
+
   
 +
// Start RMIRemoteSession on the server and create an RMIConnection
 
  RMIConnection rmiConnection = null;
 
  RMIConnection rmiConnection = null;
 
  try {
 
  try {
     rmiConnection = new RMIConnection(
+
     rmiConnection = new RMIConnection(serverManager.createRemoteSessionController());
        serverManager.createRemoteSessionController()
+
    );
+
 
  }  
 
  }  
 
  catch (RemoteException exception) {
 
  catch (RemoteException exception) {
 
     System.out.println("Error in invocation " + exception.toString());
 
     System.out.println("Error in invocation " + exception.toString());
 
  }
 
  }
  '''// Create a remote session which we can use as a normal EclipseLink session'''
+
   
 +
// Create a remote session which we can use as a normal EclipseLink session
 
  Session session = rmiConnection.createRemoteSession();
 
  Session session = rmiConnection.createRemoteSession();
  
 
+
</soure>
  
  
Line 454: Line 434:
  
 
[[Category: EclipseLink User's Guide]]
 
[[Category: EclipseLink User's Guide]]
[[Category: Draft]]
+
[[Category: Release 1]]
[[Category: Concept]]
+
[[Category: Task]]

Latest revision as of 11:13, 23 July 2012

Elug draft icon.png For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/


For information on the various types of session available, see Session Types.

Each EclipseLink session is contained within a sessions configuration (sessions.xml) file. You can create a sessions configuration using the Workbench or Java code. We recommend that you use the workbench to create and manage your sessions (see Creating a Sessions Configuration).

Alternatively, you can create sessions in Java. For more information on creating sessions in Java, see EclipseLink API Reference.

After you create a session, you must configure its various options (see Configuring a Session). After configuring the session, you can use it in your application to manage persistence (see Acquiring and Using Sessions at Run Time).


[edit] Creating a Sessions Configuration

The Workbench lets you create session instances and save them in the sessions.xml file. These tools represent the sessions.xml file as a sessions configuration. Individual session instances are contained within the sessions configuration. You can create multiple sessions configurations, each corresponding to its own uniquely named sessions.xml file.

We recommend that you use the workbench to create and manage sessions. It is the most efficient and flexible approach to session management. For more information about the advantages of this approach, see Session Configuration and the sessions.xml File.

Workbench displays sessions configurations and their contents in the Navigator window. When you select a session configuration, its attributes are displayed in the Editor window.

The Sessions Configurations in Navigator Window figure calls out the following user interface elements:

  1. Sessions Configuration
  2. Database Session
  3. Relational Server Session
  4. Connection Pool
  5. EIS Server Session
  6. XML Session
  7. Session Broker


Sessions Configurations in Navigator Window

Sessions Configurations in Navigator Window


[edit] How to Create a Sessions Configuration Using Workbench

To create an EclipseLink sessions configuration (sessions.xml file), use this procedure:

  1. Click New New Project button on the toolbar and select Sessions Configuration.
    You can also create a new sessions configuration by selecting File > New > Session Configuration from the menu, or by clicking Create New Sessions Configuration New Sessions Configuration button in the standard toolbar.
  2. The new sessions configuration element appears in the Navigator window; the Sessions Configuration property sheet appears in the Editor window.
    Enter data in each field on the Sessions Configuration property sheet, as Configuring a Sessions Configuration describes.


[edit] Configuring a Sessions Configuration

Each EclipseLink sessions configuration (sessions.xml file) can contain multiple sessions and session brokers. In addition, you can specify a classpath for each sessions configuration that applies to all the sessions it contains.


[edit] How to Configure a Sessions Configuration Using Workbench

To configure a session configuration, use this procedure:

  1. Select the session configuration in the Navigator. Its properties appear in the Editor.
    Sessions Configuration Property Sheet
    Sessions Configuration Property Sheet

  2. Enter data in each field on the Sessions Configuration property sheet.


Use the following information to enter data in each field of the Sessions configuration property sheet:

Field Description
Project Save Location Click Change and select the directory in which to save the sessions configuration.
Classpath

Lists the JAR or ZIP files that contain the compiled Java classes on which this sessions configuration depends for features that require an external Java class (for example, session event listeners).

  • To add a JAR or ZIP file, click Add Entries or Browse add the file.
  • To remove a JAR or ZIP file, select the file and click Remove.
  • To change the order in which EclipseLink searches these JAR or ZIP files, select a file and click Up to move it forward or click Down to move it back in the list.
Sessions for sessions configuration name

Lists the available sessions defined in this sessions configuration:

  • To add a session, click Add Session.
  • To remove a session, select the session and click Remove.
  • To rename a session, select the session and click Rename.

For more information on creating sessions using Workbench, see the following:


See Also:

Configuring a Sessions Configuration


[edit] Creating a Server Session

We recommend that you create server sessions using the Workbench (see How to Create a Server Session Using Workbench).

After you create a server session, you create a client session by acquiring it from the server session (see Acquiring a Client Session).


[edit] How to Create a Server Session Using Workbench

Before you create a server session, you must first create a sessions configuration (see Creating a Sessions Configuration).

To create a new EclipseLink server session, use this procedure:

  1. Select the sessions configuration in the Navigator window in which you want to create a session.
  2. Click Add Session Add Session button on the toolbar. The Create New Session dialog box appears.
    You can also create a new server session by right-clicking the sessions configuration in the Navigator and selecting New > Session from the context menu, or by clicking Add Session on the Sessions Configuration property sheet.
    Create New Session Dialog Box, Server Session Option
    Create New Session Dialog Box, Server Session Option

  3. Enter data in each field on the Create New Session dialog box.


Use the following information to enter data in each field of the dialog box:

Field Description
Name Specify the name of the new session.
Use Server Platform

Check this field if you intend to deploy your application to a Java EE application server.

If you check this field, you must configure the target application server by selecting a Platform.

Platform

This option is only available if you check Use Server Platform.

Select the Java EE application server to which you will deploy your application.

EclipseLink supports the following Java EE application servers:

  • WebLogic 10.n
  • WebLogic 9.0
  • OC4J 10.1.3.n
  • SunAS 9.0
  • WebSphere 6.1
  • JBoss
  • Custom

The server platform you select is the default server platform for all sessions you create in this sessions configuration. At the session level, you can override this selection or specify a custom server platform class.

Select Data Source

Select the data source for this session configuration. Each session configuration must contain one data source. Choose one of the following:

  • Database to create a session for a relational project.
  • EIS to create a session for an EIS project.
  • XML to create a session for an XML project 1 .

See EclipseLink Project Types for more information.

Select Session Select Server Session to create a session for a single data source (including shared object cache and connection pools) for multiple clients in a three-tier application.


1 You cannot create a server session for an XML project.

[edit] How to Create a Server Session Using Java

You can create a server session in Java code using a project. You can create a project in Java code, or read a project from a project.xml file.

This example illustrates creating an instance (called serverSession) of a Server class using a Project class.


Creating a Server Session from a Project Class

 Project myProject = new Project();
 Server serverSession = myProject.createServerSession();

This example illustrates creating an instance (called serverSession) of a Server class using a Project read in from a project.xml file.

Creating a Server Session from a project.xml File Project

 Project myProject = XMLProjectReader.read("myproject.xml");
 Server serverSession = myProject.createServerSession();

This example illustrates creating a server session with a specified write connection pool minimum and maximum size (when using EclipseLink internal connection pooling). The default write connection pool minimum size is 5 and maximum size is 10.


Creating a Server Session with Custom Write Connection Pool Size

 XMLProjectReader.read("myproject.xml");
 Server serverSession = myProject.createServerSession(32, 32);


[edit] Creating Session Broker and Client Sessions

A session broker may contain both server sessions and database sessions. We recommend that you use the session broker with server sessions because server sessions are the most scalable session type.

We recommend that you create server sessions using the Workbench).

After you create and configure a session broker with server sessions, you can acquire a client session from the session broker at run time to provide a dedicated connection to all the data sources managed by the session broker for each client. For more information, see Acquiring a Client Session.


[edit] How to Create a Session Broker and Client Sessions Using Workbench

Before you create a session broker session, you must first create a sessions configuration (see Creating a Sessions Configuration) and one or more server sessions (see Creating a Server Session), or one or more database sessions (see Creating Database Sessions).

To create a new EclipseLink session broker, use this procedure:

  1. Select the sessions configuration in the Navigator window in which you want to create a session broker.
  2. Click Add Session Broker Add Session Broker button on the toolbar. The Create New Session Broker dialog box appears.
    You can also create a new session broker by right-clicking the sessions configuration in the Navigator window and selecting Add Session Broker from the context menu or by clicking Add Session Broker on the Sessions Configuration property sheet.
    Create New Session Broker Dialog Box
    Create New Session Broker Dialog Box

  3. Enter data in each field on the New Session Broker dialog box.

Use the following information to enter data in each field of the dialog box:

Field Description
Name Specify the name of the new session broker.
Use Server Platform

Check this field if you intend to deploy your application to a Java EE application server.

If you check this field, you must configure the target application server by selecting a Platform.

Platform

This option is available only if you check Use Server Platform.

Select the Java EE application server to which you will deploy your application.

EclipseLink supports the following Java EE application servers:

  • WebLogic 10.n
  • WebLogic 9.0
  • OC4J 10.1.3.n
  • SunAS 9.0
  • WebSphere 6.1
  • JBoss
  • Custom

The server platform you select is the default server platform for all sessions you create in this sessions configuration. At the session level, you can override this selection or specify a custom server platform class.

Select the sessions to Manage

Select sessions to be managed by this new session broker (from the list of available sessions) and click OK.

Note: This field appears only if the configuration contains valid sessions.


Continue with Configuring a Session.

See Also:

Creating Session Broker and Client Sessions
Configuring a Session

[edit] How to Create a Session Broker and Client Sessions Using Java

This example illustrates how you can create a session broker in Java code by instantiating a SessionBroker and registering the brokered sessions with it.

Because the session broker references other sessions, configure these sessions before instantiating the session broker. Add all required descriptors to the session, but do not initialize the descriptors or log the sessions. The session broker manages these issues when you instantiate it.


Creating a Session Broker

 Project databaseProject = new MyDatabaseProject();
 Server databaseSession = databaseProject.createServerSession();
 
 Project eisProject = new MyEISProject();
 Server eisSession = eisProject.createServerSession();
 
 SessionBroker sessionBroker = new SessionBroker();
 sessionBroker.registerSession("myDatabase", databaseSession);
 sessionBroker.registerSession("myEIS", eisSession);
 
 sessionBroker.login();


[edit] Creating Database Sessions

We recommend that you create database sessions using the Workbench (see How to Create Database Sessions Using Workbench).

After you create a database session, you can acquire and use it at run time. For more information on acquiring a database session, see Acquiring a Session from the Session Manager.


[edit] How to Create Database Sessions Using Workbench

Before you create a database session, you must first create a sessions configuration.

To create a new EclipseLink database session, use this procedure:

  1. Select the session configuration in the Navigator window in which you want to create a session.
  2. Click Add Session Add Session button. on the toolbar. The Create New Session dialog box appears.
    You can also create a new configuration by right-clicking the sessions configuration in the Navigator window and selecting New > Session from the context menu.
    Create New Session Dialog Box, Database Session Option
    Create New Session Dialog Box, Database Session Option

  3. Complete each field on the Create New Session dialog box.

Use the following information to enter data in each field of the dialog box:

Field Description
Name Specify the name of the new session.
Use Server Platform

Check this field if you intend to deploy your application to a Java EE application server.

If you check this field, you must configure the target application server by selecting a Platform.

Platform

This option is available only if you check Use Server Platform.

Select the Java EE application server to which you will deploy your application.

EclipseLink supports the following Java EE application servers:

  • WebLogic 10.n
  • WebLogic 9.0
  • OC4J 10.1.3.n
  • SunAS 9.0
  • WebSphere 6.1
  • JBoss
  • Custom

The server platform you select is the default server platform for all sessions you create in this sessions configuration. At the session level, you can override this selection or specify a custom server platform class.

Select Data Source

Select the data source for this session configuration. Each session configuration must contain one data source. Choose one of the following:

  • Database to create a session for a relational project.
  • EIS to create a session for an EIS project.
  • XML to create a session for an XML project.

See EclipseLink Project Types for more information.

Select Session Select Database Session to create a session for a single database (including shared object cache and connection pools) for a single client suitable for simple applications or prototyping.


Enter the necessary information and click OK.

Workbench window appears, showing the database session in the Navigator window.

Continue with Configuring a Session.

[edit] How to Create Database Sessions Using Java

You can create an instance of the DatabaseSession class in Java code using a Project. You can create a project in Java code or read a project from a project.xml file.

This example illustrates creating a DatabaseSession using a Project class.


Creating a Database Session from a Project Class

 Project myProject = new Project();
 DatabaseSession databaseSession = myProject.createDatabaseSession();

This example illustrates creating a DatabaseSession using a Project read in from a project.xml file.


Creating a Database Session from a project.xml File Project

 Project myProject = XMLProjectReader.read("myproject.xml");
 DatabaseSession databaseSession = myProject.createDatabaseSession();


[edit] Creating Remote Sessions

Remote sessions are acquired through a remote connection to their server-side session. Remote sessions are acquired through Java code on the remote client. The server-side session must also be registered with an org.eclipse.persistence.remote.ejb.RemoteSessionController and accessible from the RMI naming service.

You create remote sessions entirely in Java code.


[edit] How to Create Remote Sessions Using Java

The Server Creating RMIRemoteSessionController for Client and Client Acquiring RMIRemoteSessionController from Server examples demonstrate how to create a remote EclipseLink session on a client that communicates with a remote session controller on a server that uses RMI. After creating the connection, the client application uses the remote session as it does with any other EclipseLink session.


[edit] Server

The Server Creating RMIRemoteSessionController for Client example shows the code you add to your application's RMI service (MyRMIServerManagerImpl) to create and return an instance of an RMIRemoteSessionController to the client. The controller sits between the remote client and the local EclipseLink session.

The RMIRemoteSessionController you create on the server is based on an EclipseLink server session. You create and configure this server session as described in Creating a Server Session and Configuring Server Sessions.


Server Creating RMIRemoteSessionController for Client

 RMIRemoteSessionController controller = null;
 try {
     // Create instance of RMIRemoteSessionControllerDispatcher which implements
     // RMIRemoteSessionController. The constructor takes an EclipseLink session as a parameter
     controller = new RMIRemoteSessionControllerDispatcher (localEclipseLinkSession);
 } 
 catch (RemoteException exception) {
     System.out.println("Error in invocation " + exception.toString());
 }
 return controller;

[edit] Client

The client-side code gets a reference to the application's RMI service (in this example it is called MyRMIServerManager) and uses this code to get the RMIRemoteSessionController running on the server. The reference to the session controller is then used to create the RMIConnection from which it acquires a remote session.


Client Acquiring RMIRemoteSessionController from Server

 MyRMIServerManager serverManager = null;
 
 // Set the client security manager
 try {
     System.setSecurityManager(new MyRMISecurityManager());
 } 
 catch(Exception exception) {
     System.out.println("Security violation " + exception.toString());
 }
 // Get the remote factory object from the Registry
 try {
     serverManager = (MyRMIServerManager) Naming.lookup("SERVER-MANAGER");
 } 
 catch (Exception exception) {
     System.out.println("Lookup failed " + exception.toString());
 }
 
 // Start RMIRemoteSession on the server and create an RMIConnection
 RMIConnection rmiConnection = null;
 try {
     rmiConnection = new RMIConnection(serverManager.createRemoteSessionController());
 } 
 catch (RemoteException exception) {
     System.out.println("Error in invocation " + exception.toString());
 }
 
 // Create a remote session which we can use as a normal EclipseLink session
 Session session = rmiConnection.createRemoteSession();
 
</soure>
 
 
----
''[[EclipseLink User's Guide Copyright Statement|Copyright Statement]]''
 
 
[[Category: EclipseLink User's Guide]]
[[Category: Release 1]]
[[Category: Task]]