Changeset 5071 for trunk/doc/src/docbook/developerdoc/plugin_developer.xml
- Timestamp:
- Aug 21, 2009, 8:17:57 AM (14 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/src/docbook/developerdoc/plugin_developer.xml
r5013 r5071 4429 4429 </sect2> 4430 4430 4431 <sect2 id="plugin_developer.other.logging"> 4432 <title>Logging plug-ins</title> 4433 4434 <para> 4435 BASE provides a plug-in mechanism for logging changes that are made to items. 4436 This plug-in mechanism is not the same as the regular plug-in API. That is, you do not 4437 have worry about user interaction or implementing the <interfacename 4438 docapi="net.sf.basedb.core.plugin">Plugin</interfacename> interface. 4439 </para> 4440 4441 <para> 4442 The logging mechanism works on the data layer level and hooks into 4443 callbacks provided by Hibernate. <interfacename 4444 docapi="net.sf.basedb.core.log">EntityLogger</interfacename>:s are used to 4445 extract relevant information from Hibernate and create log entries. 4446 While it is possible to have a generic logger it is usually better 4447 to have different implementations depending on the type of entity that 4448 was changed. For example, a change in a child item should, for usability 4449 reasons, be logged as a change in the parent item. Entity loggers 4450 are created by a <interfacename 4451 docapi="net.sf.basedb.core.log">LogManagerFactory</interfacename>. All changes 4452 made in a single transaction are usually collected by a <interfacename 4453 docapi="net.sf.basedb.core.log">LogManager</interfacename> which is also 4454 created by the factory. 4455 </para> 4456 4457 <sect3 id="plugin_developer.other.logmanagerfactory"> 4458 <title>The LogManagerFactory interface</title> 4459 4460 <para> 4461 Which <interfacename 4462 docapi="net.sf.basedb.core.log">LogManagerFactory</interfacename> to use 4463 is configured in <filename>base.config</filename> (See <xref 4464 linkend="appendix.base.config.log"/>). A single factory instance is created 4465 when BASE starts and is used for the lifetime of the virtual machine. The 4466 factory implementation must of course be thread-safe. Here is a list of 4467 the methods the factory must implement: 4468 </para> 4469 4470 <variablelist> 4471 <varlistentry> 4472 <term> 4473 <methodsynopsis language="java"> 4474 <modifier>public</modifier> 4475 <type>LogManager</type> 4476 <methodname>getLogManager</methodname> 4477 <methodparam> 4478 <type>LogControl</type> 4479 <parameter>logControl</parameter> 4480 </methodparam> 4481 </methodsynopsis> 4482 </term> 4483 <listitem> 4484 <para> 4485 Creates a log manager for a single transaction. Since a transaction 4486 is not thread-safe the log manager implementation doesn't have to 4487 be either. The factory has the possibility to create new log managers 4488 for each transaction. 4489 </para> 4490 </listitem> 4491 </varlistentry> 4492 4493 <varlistentry> 4494 <term> 4495 <methodsynopsis language="java"> 4496 <modifier>public</modifier> 4497 <type>boolean</type> 4498 <methodname>isLoggable</methodname> 4499 <methodparam> 4500 <type>Object</type> 4501 <parameter>entity</parameter> 4502 </methodparam> 4503 </methodsynopsis> 4504 </term> 4505 <listitem> 4506 <para> 4507 Checks if changes to the given entity should be 4508 logged or not. For performance reasons, it usually makes sense to 4509 not log everything. For example, the database logger implementation 4510 only logs changes if the entity implements the <interfacename 4511 docapi="net.sf.basedb.core.data">LoggableData</interfacename> 4512 interface. The return value of this method should be consistent 4513 with <methodname>getEntityLogger()</methodname>. 4514 </para> 4515 </listitem> 4516 </varlistentry> 4517 4518 <varlistentry> 4519 <term> 4520 <methodsynopsis language="java"> 4521 <modifier>public</modifier> 4522 <type>EntityLogger</type> 4523 <methodname>getEntityLogger</methodname> 4524 <methodparam> 4525 <type>LogManager</type> 4526 <parameter>logManager</parameter> 4527 </methodparam> 4528 <methodparam> 4529 <type>Object</type> 4530 <parameter>entity</parameter> 4531 </methodparam> 4532 </methodsynopsis> 4533 </term> 4534 <listitem> 4535 <para> 4536 Create or get an entity logger that knows how to log 4537 changes to the given entity. If the entity should not be 4538 logged, <constant>null</constant> can be returned. This method 4539 is called for each modified item in the transaction. 4540 </para> 4541 </listitem> 4542 </varlistentry> 4543 </variablelist> 4544 4545 </sect3> 4546 4547 <sect3 id="plugin_developer.other.logmanager"> 4548 <title>The LogManager interface</title> 4549 4550 <para> 4551 A new log manager is created for each transaction. The log manager 4552 is responsible for collecting all changes made in the transaction 4553 and store those changes in the appropriate place. The interface doesn't define 4554 any methods for this collection, since each implementation may have 4555 very different needs. 4556 </para> 4557 4558 <variablelist> 4559 <varlistentry> 4560 <term> 4561 <methodsynopsis language="java"> 4562 <modifier>public</modifier> 4563 <type>LogControl</type> 4564 <methodname>getLogControl</methodname> 4565 </methodsynopsis> 4566 </term> 4567 <listitem> 4568 <para> 4569 Get the log control object that was supplied by the BASE core 4570 when the transaction was started. The log controller contains 4571 methods for accessing information about the transaction, such 4572 as the logged in user, executing plug-in, etc. It can also 4573 be used to execute queries against the database to get 4574 even more information. 4575 </para> 4576 4577 <warning> 4578 <para> 4579 Be careful about the queries that are executed by the log 4580 controller. Since all logging code is executed at flush 4581 time in callbacks from Hibernate we are not allowed to 4582 use the regular session. Instead, all queries are sent 4583 through the stateless session. The stateless session has no 4584 caching functionality which means that Hibernate will use 4585 extra queries to load associations. Our recommendation is 4586 to avoid quires that return full entities, use scalar 4587 queries instead to just load the values that are needed. 4588 </para> 4589 </warning> 4590 </listitem> 4591 </varlistentry> 4592 <varlistentry> 4593 <term> 4594 <methodsynopsis language="java"> 4595 <modifier>public</modifier> 4596 <void/> 4597 <methodname>afterCommit</methodname> 4598 </methodsynopsis> 4599 </term> 4600 <term> 4601 <methodsynopsis language="java"> 4602 <modifier>public</modifier> 4603 <void/> 4604 <methodname>afterRollback</methodname> 4605 </methodsynopsis> 4606 </term> 4607 <listitem> 4608 Called after a successful commit or after a rollback. Note 4609 that the connection to the database has been closed at this 4610 time and it is not possible to save any more information to 4611 it at this time. 4612 </listitem> 4613 </varlistentry> 4614 </variablelist> 4615 </sect3> 4616 4617 <sect3 id="plugin_developer.other.entitylogger"> 4618 <title>The EntityLogger interface</title> 4619 4620 <para> 4621 An entity logger is responsible for extracting the changes 4622 made to an entity and converting it to something that is useful 4623 as a log entry. In most cases, this is not very complicated, but 4624 in some cases, a change in one entity should actually be logged 4625 as a change in a different entity. For example, changes to 4626 annotations are handled by the <classname 4627 docapi="net.sf.basedb.core.log.db">AnnotationLogger</classname> which 4628 which log it as a change on the parent item. 4629 </para> 4630 4631 <variablelist> 4632 <varlistentry> 4633 <term> 4634 <methodsynopsis language="java"> 4635 <modifier>public</modifier> 4636 <void/> 4637 <methodname>logChanges</methodname> 4638 <methodparam> 4639 <type>LogManager</type> 4640 <parameter>logManager</parameter> 4641 </methodparam> 4642 <methodparam> 4643 <type>EntityDetails</type> 4644 <parameter>details</parameter> 4645 </methodparam> 4646 </methodsynopsis> 4647 </term> 4648 <listitem> 4649 <para> 4650 This method is called whenever a change has been detected 4651 in an entity. The <varname>details</varname> variable contains 4652 information about the entity and, to a certain degree, 4653 what changes that has been made. 4654 </para> 4655 </listitem> 4656 </varlistentry> 4657 </variablelist> 4658 </sect3> 4659 </sect2> 4431 4660 </sect1> 4432 4661
Note: See TracChangeset
for help on using the changeset viewer.
