From dna-commits at lists.jboss.org Thu Apr 30 18:12:45 2009 Content-Type: multipart/mixed; boundary="===============7796121288330436734==" MIME-Version: 1.0 From: dna-commits at lists.jboss.org To: dna-commits at lists.jboss.org Subject: [dna-commits] DNA SVN: r870 - in trunk: docs/gettingstarted/src/main/docbook/en-US and 3 other directories. Date: Thu, 30 Apr 2009 18:11:02 -0400 Message-ID: --===============7796121288330436734== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: rhauch Date: 2009-04-30 18:11:02 -0400 (Thu, 30 Apr 2009) New Revision: 870 Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/custom_sequence= rs.xml trunk/docs/gettingstarted/src/main/docbook/en-US/content/understanding_d= na.xml trunk/docs/gettingstarted/src/main/docbook/en-US/master.xml trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml trunk/docs/reference/src/main/docbook/en-US/content/jcr.xml trunk/docs/reference/src/main/docbook/en-US/content/repositories.xml trunk/docs/reference/src/main/docbook/en-US/content/testing.xml trunk/docs/reference/src/main/docbook/en-US/custom.dtd trunk/docs/reference/src/main/docbook/en-US/master.xml trunk/pom.xml Log: DNA-385 Documentation Updates for 0.4 Reviewed and edited both documents to bring everything up to the current st= ate of the code. Most parts were still accurate, but there were a number o= f places there were minor changes and quite a few sections that needed more= work. Pending errors or other changes/suggestions, the docs are complete and accu= rate for this release. Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/custom_s= equencers.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/docs/gettingstarted/src/main/docbook/en-US/content/custom_sequenc= ers.xml 2009-04-30 18:18:49 UTC (rev 869) +++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/custom_sequenc= ers.xml 2009-04-30 22:11:02 UTC (rev 870) @@ -73,12 +73,12 @@ org.jboss.dna dna-common - 0.1 + 0.4 org.jboss.dna dna-graph - 0.1 + 0.4 org.slf4j @@ -122,7 +122,7 @@ org.jboss.dna dna-repository - 0.1 + 0.4 test @@ -136,7 +136,7 @@ org.apache.jackrabbit jackrabbit-api - 1.3.3 + 1.4 test @@ -153,7 +153,7 @@ org.apache.jackrabbit jackrabbit-core - 1.3.3 + 1.4.5 test Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/understa= nding_dna.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/docs/gettingstarted/src/main/docbook/en-US/content/understanding_= dna.xml 2009-04-30 18:18:49 UTC (rev 869) +++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/understanding_= dna.xml 2009-04-30 22:11:02 UTC (rev 870) @@ -45,9 +45,10 @@ Architecture - The architecture for JBoss DNA consists of several major compone= nts that will be built on top of standard APIs, + The planned architecture for JBoss DNA consists of several major= components that will be built on top of standard APIs, including JCR, JDBC, JNDI and HTTP. The goal is to allow these compo= nents to be assembled as needed and add value on top - of other DNA components or third-party systems that support these st= andard APIs. + of other DNA components or third-party systems that support these st= andard APIs. Not all of these components exist + yet - at the moment we're focusing on completing our JCR-compliant i= mplementation using our connector framework. @@ -57,18 +58,87 @@ - As shown in the diagram above, the major components are (starting at= the top): + Let's go over each of these components, starting from the bottom of = the diagram: + DNA Connectors + are used to communicate with these external sources of informa= tion, whether there's one source (like a database) in + which all of the content is stored, or information is being federat= ed from multiple sources. The connector's + job is to interact with the external source and map the source's in= formation into the lower-level graph language used by + JBoss DNA. Connectors also may optionally participate in distribute= d transactions by exposing an XAResource. + In summary, then, the connector API isolates all of the other compon= ents from how the graph are persisted. + We've built a number of connectors already, but we're always interes= ted in adding more. Or, you could write your own, + since we've designed the connector API to be as straightforward as p= ossible. + + + + + DNA Federation + is actually special repository connector that accesses informa= tion from multiple other sources via connectors, + making all this information look like it is part of a single, unifi= ed graph. Because it is a connector, + it can be used wherever connectors can be used. And because it use= s connectors, the federation connector + makes it possible to integrate a wide variety of external systems, l= ike other JCR + repositories, databases, applications, and services. + + + + + DNA JCR + is an implementation of the JCR API that accesses the content = from a single connector. Our implementation has come a long + with in the 0.4 release, and is nearly Level 1 and Level 2 compliant= . Finishing the remaining features, including search + and query, are major objectives of our next release. + + + + + DNA Sequencers + are pluggable components that automatically process content (t= ypically files) that are uploaded into the repository, + looking for useful structure and information in that content. When = a file is uploaded to the repository, JBoss DNA automatically + figures out which sequencer(s) should be run, and then runs them. E= ach sequencer, then, extracts the meaningful information + from the file's content and places that structure in the repository.= Once this information is in + the repository, it can be viewed, edited, analyzed, searched, = and related to other content. DNA defines a Java + interface that sequencers must implement. DNA sequencers opera= te upon any JCR-compliant repository. + We have a number of sequencers, but plan on adding more over time. = Like connectors, the Sequencer API makes it very + simple to write sequencers for your own file types. + + + + + DNA Analyses + are similar to sequencers, except they process the graph struc= ture rather than uploaded files. You can think of them + as report generators, where they process some area of the repositor= y and generate output. The output doesn't take the + form of a document or file, but rather more graph content that is th= en stored in the repository, where it can be accessed + and searched just like any other content. We're still figuring out = how to best make analyzers easy to write and use, + and have been focused on other aspects of the architecture. But we'= re planning on using analyzers for dependency, + similarity, and statistical analyses. + + + + + DNA Maven + is a classloader library compatible with Maven 2 project depen= dencies. This allows the creation of Java ClassLoader + instances using Maven 2 style paths, and all dependencies are = transitively managed and included. This exists but is + still immature. + + + + + + The remaining parts of the architecture haven't yet been started, but t= hey service important purposes for a complete metadata + repository system. + + + DNA Eclipse Plugins - enable Eclipse users to access the contents of a JBoss DNA rep= ository. + enable Eclipse users to access the contents of a JBoss DNA rep= ository. This is a planned component that may be started soon. DNA JDBC Driver provides a driver implementation, allowing JDBC-aware applicat= ions to connect to and use a JBoss DNA repository. + This is a planned component on our roadmap. @@ -106,74 +176,19 @@ - DNA Sequencers - are pluggable components that make it possible for content to = be uploaded to the repository and automatically - processed to extract meaningful structure and place that struc= ture in the repository. Once this information is in - the repository, it can be viewed, edited, analyzed, searched, = and related to other content. DNA defines a Java - interface that sequencers must implement. DNA sequencers opera= te upon any JCR-compliant repository. - - - - - DNA Analyses - are pluggable components that analyze content and the relation= ships between content to generate reports or to answer - queries. DNA will include some standard analyzers, like depend= ency analysis and similarity analysis, that are - commonly needed by many different solutions. DNA analyzers ope= rate upon any JCR-compliant repository. - - - - DNA Views are definitions of how types of information are to be presente= d in a user interface to allow for creation, reading, editing, and deletion of information. DNA view definitions con= sist of data stored in a JCR repository, and as such views can be easily added, changed or removed entirely by usin= g the DNA Web Application, requiring no programming. - - - DNA Repositories - is an implementation of the JCR API that builds the content wi= thin the repository by accessing and integrating - information from one or more sources. = - - - - - DNA Federation - is a special repository connector that accesses information fr= om multiple sources and makes it accessible = - as if it were a single repository. DNA Federation allows the integra= tion of external systems, like other JCR - repositories, databases, applications, and services. - - - - - DNA Connectors - are used to communicate with these external sources of informa= tion. In the federation engine, each source is able to - contribute node structure and node properties to any part of t= he federated graph, although typically many connectors - will contribute most of their information to isolated subgraph= s. The result is that integration from a wide range of - systems can be integrated and accessed through the DNA Web App= lication, DNA Publishing Server, and DNA WebDAV - Server. Connectors also may optionally participate in distribu= ted transactions by exposing an XAResource. - - - - - DNA Maven - is a classloader library compatible with Maven 2 project depen= dencies. This allows the creation of Java ClassLoader - instances using Maven 2 style paths, and all dependencies are = transitively managed and included. - - Continue reading the rest of this chapter for more detail about the - sequencing framework - available in this release, or the - federation engine - and - connectors - that will be the focus of the next release. Or, skip to the - examples - to see how to start using JBoss DNA &versionNumber; - today. = + sequencing framework available i= n this release, or the federation engine + and connectors. Or, s= kip to the examples + to see how to start using JBoss DNA &versionNumber; today. = @@ -190,7 +205,7 @@ policies, UML, MetaMatrix models, etc. JBoss DNA sequencers sit on top of existing JCR repositories (includ= ing federated repositories) - they basically extract - more useful information from what's already stored in the repository= . And they use the existing JCR versioning system. Each + more useful information from what's already stored in the repository= . And they use the existing JCR event and versioning system. Each sequencer typically processes a single kind of file format or a sing= le kind of content. The following sequencers are included in JBoss DNA: @@ -201,9 +216,7 @@ writes that image metadata to the repository. It gets the file= format, image resolution, number of bits per pixel (and optionally number of images), comments and physical resol= ution from JPEG, GIF, BMP, PCX, PNG, IFF, RAS, PBM, PGM, PPM, and PSD files. (This sequencer may be improved in th= e future to also extract EXIF metadata from JPEG - files; see - DNA-26= - .) + files; see DNA-26.) @@ -212,10 +225,41 @@ - A sequencer that processes the contents of an MP3 audio file= , extracts the metadata for the file, and then writes that image metadata to the repository. It gets the titl= e, author, album, year, and comment. = (This sequencer may be improved in the future to also extract = other ID3 metadata from other audio file formats; see - DNA-26= - .) + DNA-66= .) + + + ZIP Archive Sequencer + - Process ZIP archive files to extract (explode) the contents = into the repository. + + + + + Java Source File Sequencer + - Process Java source files to extract the class structure (in= cluding annotations) into the repository. + + + + + XML File Sequencer + - Process XML files to extract the structure into the reposito= ry. + + + + + Microsoft Office File Sequencer + - Process Microsoft Office documents, spreadsheets, and presen= tation files to extract their basic structure. + For example, the sequencer extracts the outline of a document, or th= e title and outline of a presentation. = + + + + + JCR Compact Node Definition (CND) Fi= le Sequencer + - Process the CND files defined by JCR, extracting the various= node types with their property definitions and child + node definitions. + + @@ -224,6 +268,16 @@ + Data Definition Language (DDL) Seque= ncer + - Process various dialects of DDL, including that from Oracle,= SQL Server, MySQL, PostgreSQL, and others. May need + to be split up into a different sequencer for each dialect. Th= is sequencer is being developed as part of a + Google Summer of Code 2009 project. (See + DNA-26= + ) + + + + XML Schema Document (XSD) Sequencer<= /emphasis> - Process XSD files and extract the various elements, attribut= es, complex types, simple types, groups, and other information. (See @@ -259,14 +313,6 @@ - ZIP Archive Sequencer - - Process ZIP archive files to extract (explode) the contents = into the repository. (See - DNA-63= - ) - - - - Java Archive (JAR) Sequencer - Process JAR files to extract (explode) the contents into the= classes and file resources. (See DNA-64= @@ -284,14 +330,6 @@ - Java Source File Sequencer - - Process Java source files to extract the class structure (in= cluding annotations) into the repository. (See - DNA-51= - ) - - - - PDF Sequencer - Process PDF files to extract the document metadata, includin= g table of contents. (See DNA-50= @@ -309,15 +347,6 @@ - Data Definition Language (DDL) Seque= ncer - - Process various dialects of DDL, including that from Oracle,= SQL Server, MySQL, PostgreSQL, and others. May need - to be split up into a different sequencer for each dialect. (S= ee - DNA-26= - ) - - - - MP3 and MP4 Sequencer - Process MP3 and MP4 audio files to extract the name of the s= ong, artist, album, track number, and other metadata. (See @@ -342,7 +371,7 @@ to access that information as if it were all stored in a single JCR = repository, but to really leave the information where it is. Why not just copy or move the information into a JCR repository?= Moving it is probably pretty difficult, since most = - likely there are existing applications that rely upon that information = being where it is. All of those applications + likely existing applications rely upon that information being where it = is. All of those applications would break or have to change. And copying the information means that = we'd have to continually synchronize the changes. This not only is a lot of work, but it often creates issues with knowin= g which information is accurate. @@ -500,11 +529,6 @@ (and possibly rewritten) such that it can be pushed down to all th= e appropriate sources. Also, the cached results must be consulted prior to returning the query results, as the results = from one source might have contributions from another source. - - It is hoped that the MetaMatrix query engine can be used fo= r this purpose after it is open-sourced. This engine - implements sophisticated query planning and optimization techniq= ues for working efficiently with multiple sources. - - Searching the whole federated repository is also important. Th= is allows users to simply supply a handful of search terms, and to get results that are ranked based upon how cl= ose each result is to the search terms. (Searching is very different from querying, which involves specifying the exact = semantics of what is to be searched and how the Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/master.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/docs/gettingstarted/src/main/docbook/en-US/master.xml 2009-04-30 = 18:18:49 UTC (rev 869) +++ trunk/docs/gettingstarted/src/main/docbook/en-US/master.xml 2009-04-30 = 22:11:02 UTC (rev 870) @@ -25,9 +25,9 @@ ~ Boston, MA 02110-1301 USA --> - - + + + ]> @@ -35,7 +35,7 @@ Getting Started Guide &versionNumber; &versionNumber; - 1 + 4 Modified: trunk/docs/reference/src/main/docbook/en-US/content/introduction.= xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml 20= 09-04-30 18:18:49 UTC (rev 869) +++ trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml 20= 09-04-30 22:11:02 UTC (rev 870) @@ -170,7 +170,7 @@ The JBoss DNA project - is building unified metadata repository system that is compliant with= JCR. Nearly all of these capabilities are to be hidden + is building unified metadata repository system that will be compliant= with JCR. Nearly all of these capabilities are to be hidden below the JCR API and involve automated processing of the information= in the repository. Thus, JBoss DNA can add value to existing repository implementations. For example, JCR repositories of= fer the ability to upload files into the repository and have the file content indexed for search purposes. JBoss DNA also def= ines a library for "sequencing" content - to extract Modified: trunk/docs/reference/src/main/docbook/en-US/content/jcr.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/docs/reference/src/main/docbook/en-US/content/jcr.xml 2009-04-30 = 18:18:49 UTC (rev 869) +++ trunk/docs/reference/src/main/docbook/en-US/content/jcr.xml 2009-04-30 = 22:11:02 UTC (rev 870) @@ -101,6 +101,15 @@ + JCR Support + + JBoss DNA currently supports most of the Level 1 and Level 2 feature se= t defined by the JSR-170 specification. + Queries, which are part of Level 1, are not implemented, nor are all of= the update methods that make up Level 2. + So while the current implementation provides many of the features that = may be needed by an application, we really hope + that this release will allow you to give us some feedback on what we ha= ve so far. + + + Summary In this chapter, we covered how to use JCR with JBoss DNA. Now that yo= u know how JBoss DNA repositories work, Modified: trunk/docs/reference/src/main/docbook/en-US/content/repositories.= xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/docs/reference/src/main/docbook/en-US/content/repositories.xml 20= 09-04-30 18:18:49 UTC (rev 869) +++ trunk/docs/reference/src/main/docbook/en-US/content/repositories.xml 20= 09-04-30 22:11:02 UTC (rev 870) @@ -167,6 +167,24 @@ existing connectors and show= how to create your own connectors. + + Workspaces + The previous section talked about how connector expose their infor= mation through the graph language of JBoss DNA. + This is true, except that we didn't dive into too much of the detail. = JBoss DNA graphs have the notion of workspaces + in which the content appears, and its very easy for clients using the g= raph to switch between workspaces. In fact, + workspaces differ from each other in that they provide different views = of the same information. + + Consider a source control system, like SVN or CVS. These systems = provide different views of the source code: + a mainline development branch as well as other branches (or tags) commo= nly used for releases. So, just like one source + file might appear in the mainline branch as well as the previous two re= lease branches, a node in a repository source + might appear in multiple workspaces. + + + However, each connector can kind of decide how (or whether) it uses wor= kspaces. For example, there may be no overlap + in the content between workspaces. Or a connector might only expose a = single workspace (in other words, there's only one + "default" workspace). + + Repository Service The JBoss DNA &RepositoryService; is the component that manages th= e repository sources @@ -309,6 +327,11 @@ cached by other, higher-level components. The default value of nu= ll implies that this source does not define a specific duration for caching information provided by this repository sourc= e. + + defaultWorkspaceName + Optional property that is initialized to an empty string and= which defines the name for the workspace that will be used by default + if none is specified. + @@ -373,6 +396,19 @@ cached by other, higher-level components. The default value of nu= ll implies that this source does not define a specific duration for caching information provided by this repository sourc= e. + + nameOfDefaultWorkspace + Optional property that is initialized to an empty string and= which defines the name for the workspace that will be used by default + if none is specified. + + + predefinedWorkspaceNames + Optional property that defines the names of the workspaces t= hat exist and that are available for use without having to create them. + + + creatingWorkspacesAllowed + Optional property that is by default 'true' that defines whe= ther clients can create new workspaces. + @@ -422,22 +458,25 @@ cache and federated sources. This graph structure that is expected at= this location is as follows: - - - - /= " /> - - - + + + + /" /> + + + /" /> /" /> /" /> - - + + + + ]]> @@ -488,6 +527,11 @@ &RepositoryLibrary;. + configurationWorkspaceName + The name of the workspace in the configuration &RepositorySo= urce; with the content defining + how this federated repository is to be set up and configured. + + configurationSourcePath The path to the node in the configuration repository below w= hich a "dna:federation" node exists with the = graph structure describing how this federated repository is to be = configured. @@ -601,7 +645,7 @@ org.jboss.dna dna-graph - 0.3 + 0.4 ]]> @@ -616,14 +660,14 @@ org.jboss.dna dna-graph - 0.3 + 0.4 test-jar test org.jboss.dna dna-common - 0.3 + 0.4 test-jar test @@ -907,7 +951,7 @@ information, although the connector should still perform as expected w= hen requests have incomplete locations. - Types of Requests + Types of Node Operation Requests @@ -921,62 +965,76 @@ ReadNodeRequest - A request to read from the source a node's properties and children. + A request to read from the named workspace in the source a node's = properties and children. The node may be specified by path and/or by identification propert= ies. The connector returns all properties and the locations for all chi= ldren, - or sets a &PathNotFoundException; error on the request if the node= did not exist. + or sets a &PathNotFoundException; error on the request if the node= did not exist in the workspace. If the node is found, the connector sets on the request the actual= location of the node (including the path and identification properties). + The connector sets a &InvalidWorkspaceException; error on the requ= est if the named workspace does not exist. + VerifyNodeExistsRequest + + A request to verify the existance of a node at the specified locat= ion in the named workspace of the source. + The connector returns all the actual location for the node if it e= xists, or + sets a &PathNotFoundException; error on the request if the node do= es not exist in the workspace. + The connector sets a &InvalidWorkspaceException; error on the requ= est if the named workspace does not exist. + + + ReadAllPropertiesRequest - A request to read from the source all of the properties of a node. + A request to read from the named workspace in the source all of th= e properties of a node. The node may be specified by path and/or by identification propert= ies. The connector returns all properties that were found on the node, - or sets a &PathNotFoundException; error on the request if the node= did not exist. + or sets a &PathNotFoundException; error on the request if the node= did not exist in the workspace. If the node is found, the connector sets on the request the actual= location of the node (including the path and identification properties). + The connector sets a &InvalidWorkspaceException; error on the requ= est if the named workspace does not exist. ReadPropertyRequest - A request to read from the source a single property of a node. + A request to read from the named workspace in the source a single = property of a node. The node may be specified by path and/or by identification propert= ies, and the property is specified by name. The connector returns the property if found on the node, - or sets a &PathNotFoundException; error on the request if the node= or property did not exist. + or sets a &PathNotFoundException; error on the request if the node= or property did not exist in the workspace. If the node is found, the connector sets on the request the actual= location of the node (including the path and identification properties). + The connector sets a &InvalidWorkspaceException; error on the requ= est if the named workspace does not exist. ReadAllChildrenRequest - A request to read from the source all of the children of a node. + A request to read from the named workspace in the source all of th= e children of a node. The node may be specified by path and/or by identification propert= ies. The connector returns an ordered list of locations for each child = found on the node, an empty list if the node had no children, - or sets a &PathNotFoundException; error on the request if the node= did not exist. + or sets a &PathNotFoundException; error on the request if the node= did not exist in the workspace. If the node is found, the connector sets on the request the actual= location of the parent node (including the path and identification propert= ies). + The connector sets a &InvalidWorkspaceException; error on the requ= est if the named workspace does not exist. ReadBlockOfChildrenRequest - A request to read from the source a block of children of a node, s= tarting with the nth children. + A request to read from the named workspace in the source a block o= f children of a node, starting with the nth chil= dren. This is designed to allow paging through the children, which is mu= ch more efficient for large numbers of children. The node may be specified by path and/or by identification propert= ies, and the block is defined by a starting index and a count (i.e., the block size). The connector returns an ordered list of locations for each of the= node's children found in the block, or an empty list if there are no children in that range. The connector also sets on the request the actual location of the = parent node (including the path and identification properties) - or sets a &PathNotFoundException; error on the request if the pare= nt node did not exist. + or sets a &PathNotFoundException; error on the request if the pare= nt node did not exist in the workspace. + The connector sets a &InvalidWorkspaceException; error on the requ= est if the named workspace does not exist. ReadNextBlockOfChildrenRequest - A request to read from the source a block of children of a node, s= tarting with the children that immediately follow + A request to read from the named workspace in the source a block o= f children of a node, starting with the children that immediately follow a previously-returned child. This is designed to allow paging through the children, which is mu= ch more efficient for large numbers of children. The node may be specified by path and/or by identification propert= ies, and the block @@ -984,7 +1042,8 @@ The connector returns an ordered list of locations for each of the= node's children found in the block, or an empty list if there are no children in that range. The connector also sets on the request the actual location of the = parent node (including the path and identification properties) - or sets a &PathNotFoundException; error on the request if the pare= nt node did not exist. + or sets a &PathNotFoundException; error on the request if the pare= nt node did not exist in the workspace. + The connector sets a &InvalidWorkspaceException; error on the requ= est if the named workspace does not exist. @@ -997,7 +1056,8 @@ nodes found in the branch. = The connector also sets on the request the actual location of the = branch's root node (including the path and identification properties). The connector sets a &PathNotFoundException; error on the request = if the node at = - the top of the branch does not exist. + the top of the branch does not exist in the workspace. + The connector sets a &InvalidWorkspaceException; error on the requ= est if the named workspace does not exist. @@ -1009,7 +1069,8 @@ will have their SNS indexes adjusted. However, if the requested l= ocation does not include a SNS index, the new node is added after all existing children, and it's SNS index is s= et accordingly.) The connector also sets on the request the actual location of the = new node (including the path and identification properties).. - The connector sets a &PathNotFoundException; error on the request = if the parent node does not exist. + The connector sets a &PathNotFoundException; error on the request = if the parent node does not exist in the workspace. + The connector sets a &InvalidWorkspaceException; error on the requ= est if the named workspace does not exist. @@ -1018,7 +1079,8 @@ A request to remove a set of properties on an existing node. The = request contains the location of the node as well as the names of the properties to be removed. The connector performs the= se changes and sets on the request the actual location (including the path and identification properties)= of the node. - The connector sets a &PathNotFoundException; error on the request = if the node does not exist. + The connector sets a &PathNotFoundException; error on the request = if the node does not exist in the workspace. + The connector sets a &InvalidWorkspaceException; error on the requ= est if the named workspace does not exist. @@ -1027,7 +1089,8 @@ A request to set or update properties on an existing node. The re= quest contains the location of the node as well as the properties to be set and those to be deleted. The connector perfo= rms these changes and sets on the request the actual location (including the path and identification properties)= of the node. - The connector sets a &PathNotFoundException; error on the request = if the node does not exist. + The connector sets a &PathNotFoundException; error on the request = if the node does not exist in the workspace. + The connector sets a &InvalidWorkspaceException; error on the requ= est if the named workspace does not exist. @@ -1036,19 +1099,23 @@ A request to change the name of a node. The connector changes the= node's name, adjusts all SNS indexes accordingly, and returns the actual locations (including the path = and identification properties) of both the original location and the new location. - The connector sets a &PathNotFoundException; error on the request = if the node does not exist. + The connector sets a &PathNotFoundException; error on the request = if the node does not exist in the workspace. + The connector sets a &InvalidWorkspaceException; error on the requ= est if the named workspace does not exist. CopyBranchRequest A request to copy a portion of a subgraph that has as its root a p= articular node, up to a maximum depth. + The request includes the name of the workspace where the original = node is located as well as the name of the + workspace where the copy is to be placed (these may be the same, b= ut may be different). The connector copies the branch from the original location, up to = the specified maximum depth, and places a copy of the node as a child of the new location. The connector also sets on the request the actual location (includ= ing the path and identification properties) of the original location as well as the location of the new copy. The connector sets a &PathNotFoundException; error on the request = if the node at = - the top of the branch does not exist. + the top of the branch does not exist in the workspace. + The connector sets a &InvalidWorkspaceException; error on the requ= est if one of the named workspaces does not exist. @@ -1059,7 +1126,8 @@ The connector also sets on the request the actual location (includ= ing the path and identification properties) of the original and new locations. The connector will adjust SNS = indexes accordingly. The connector sets a &PathNotFoundException; error on the request = if the node that is to be moved or the - new location do not exist. + new location do not exist in the workspace. + The connector sets a &InvalidWorkspaceException; error on the requ= est if the named workspace does not exist. @@ -1068,7 +1136,8 @@ A request to delete an entire branch specified by a single node's = location. The connector deletes the specified node and all nodes below it, a= nd sets the actual location, including the path and identification properties, of the node that= was deleted. - The connector sets a &PathNotFoundException; error on the request = if the node being deleted does not exist. + The connector sets a &PathNotFoundException; error on the request = if the node being deleted does not exist in the workspace. + The connector sets a &InvalidWorkspaceException; error on the requ= est if the named workspace does not exist. @@ -1082,6 +1151,60 @@
+ There are also requests that deal with workspaces: + + Types of Workspace Requests + + + + + + Name + Description + + + + + GetWorkspacesRequest + + A request to obtain the names of the existing workspaces that are = accessible to the caller. + + + + VerifyWorkspaceRequest + + A request to verify that a workspace with a particular name exists. + The connector returns the actual location for the root node if the= workspace exists, as well as the actual name of the workspace + (e.g., the default workspace name if a null name is supplied). + + + + CreateWorkspaceRequest + + A request to create a workspace with a particular name. + The connector returns the actual location for the root node if the= workspace exists, as well as the actual name of the workspace + (e.g., the default workspace name if a null name is supplied). + The connector sets a &InvalidWorkspaceException; error on the requ= est if the named workspace already exists. + + + + DestroyWorkspaceRequest + + A request to destroy a workspace with a particular name. + The connector sets a &InvalidWorkspaceException; error on the requ= est if the named workspace does not exist. + + + + CloneWorkspaceRequest + + A request to clone one named workspace as another new named worksp= ace. + The connector sets a &InvalidWorkspaceException; error on the requ= est if the original workspace does not exist, = + or if the new workspace already exists. + + + + +
Although there are over a dozen different kinds of requests, we do ant= icipate adding more in future releases. For example, DNA will likely support searching repository content in s= ources through an additional subclass of &Request;. @@ -1101,10 +1224,10 @@ - In many cases, the default implementations of the process(...)<= /code> methods are sufficient - but probably not efficient or optimum. If that is the case, simply p= rovide your own methods that perform the request - in a manner that is efficient for your source. However, if performan= ce is not a big issue, all of the concrete methods - will provide the correct behavior. And remember, you can always prov= ide better implementations later. + The &RequestProcessor; abstract class contains default implementation= s for quite a few of the process(...) methods, + and these will be sufficient but probably not ef= ficient or optimum. If you can provide a more efficient + implementation given your source, feel free to do so. However, if pe= rformance is not a big issue, all of the concrete methods + will provide the correct behavior. Keep things simple to start out - = you can always provide better implementations later. @@ -1116,7 +1239,11 @@ public void execute( final &ExecutionContext; context, final &Request; request ) throws RepositorySourceExce= ption { RequestProcessor processor =3D new RequestProcessor(context); - processor.process(request); + try { + processor.process(request); + } finally { + processor.close(); + } } If you do this, the bulk of your connector implementation may be in th= e &RequestProcessor; implementation methods. @@ -1191,8 +1318,67 @@ Just remember that under the covers, a &Graph; is just building &Reques= t; objects, submitting them to the connector, and then exposing the results. + + Using workspaces - Let's look at some examples of how the Graph API works. This first exa= mple returns a map of properties (keyed by property name) = + Let's look at some examples of how the Graph API works. This first exa= mple shows how to obtain the names of the available workspaces: + + +&Set;<&String;> workspaceNames =3D graph.getWorkspaces(); + + Once you know the name of the workspace, you can specify that the = graph should use it: + + +graph.useWorkspace("myWorkspace"); + + + From this point forward, all requests will apply to the workspace named= "myWorkspace". At any time, you can use a different workspace, + which will affect all subsequent requests made using the graph. Of cou= rse, creating a new workspace is just as easy: + + +graph.createWorkspace().named("newWorkspace"); + + This will attempt to create a workspace named "newWorkspace", whi= ch will fail if that workspace already exists. You may + want to create a new workspace with a name that should be altered if the= name you supply is already used. The following code shows + how you can do this: + + +graph.createWorkspace().namedSomethingLike("newWorkspace"); + + If there is no existing workspace named "newWorkspace", a new one= will be created with this name. However, if "newWorkspace" already + exists, this call will create a workspace with a name that is some alter= ation of the supplied name. + + + You can also clone workspaces, too: + + +graph.createWorkspace().clonedFrom("original").named("something"); + + + or + + +graph.createWorkspace().clonedFrom("original").namedSomethingLike("somethi= ng"); + + + As you can see, it's very easy to specify which workspace you want to u= se or to create new workspaces. You can also find out which workspace + the graph is currently using: + + +&String; current =3D graph.getCurrentWorkspaceName(); + + or, if you want, you can get more information about the workspace: + + +&Workspace; current =3D graph.getCurrentWorkspace(); +&String; name =3D current.getName(); +&Location; rootLocation =3D current.getRoot(); + + + + Working with nodes + + Now let's switch to working with nodes. This first example returns a m= ap of properties (keyed by property name) = for a node at a specific &Path;: @@ -1268,6 +1454,7 @@ The &Graph; interface is actually quite complete and offers a full-feat= ured approach for reading and updating a graph. For more information, see the &Graph; JavaDocs. + Summary Modified: trunk/docs/reference/src/main/docbook/en-US/content/testing.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/docs/reference/src/main/docbook/en-US/content/testing.xml 2009-04= -30 18:18:49 UTC (rev 869) +++ trunk/docs/reference/src/main/docbook/en-US/content/testing.xml 2009-04= -30 22:11:02 UTC (rev 870) @@ -129,4 +129,24 @@ to do it quickly and in a way that makes it easy to understand what the= code is supposed to do (or not do). + + Technology Compatibility Kit (TCK) tests + + Many Java specifications provide TCK test suites that can be used to = check or verify that an implementation + correctly implements the API or SPI defined by the specification. T= hese TCK tests vary by technology, but + JSR-170 does provide TCK tests that ens= ure that a JCR repository implementation exhibits the correct and expected + behavior. + + + JBoss DNA has not yet passed enough of the TCK tests to publish the re= sults. We still have to implement + queries, which is a required feature of Level 1 repositories. However= , suffice to say that JBoss DNA has passed + many of the individual tests that make up the Level 1 and Level 2 test= s, and it is a major objective of the next + release to pass the remaining Level 1 and Level 2 tests (along with so= me other optional features). + + + JBoss DNA also frequently runs the JCR unit tests from the Apache Jackr= abbit project. (Those these tests are not + the official TCK, they apparently are used within the official TCK.) T= hese unit tests are set up in the + dna-jcr-tck project. + + Modified: trunk/docs/reference/src/main/docbook/en-US/custom.dtd =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/docs/reference/src/main/docbook/en-US/custom.dtd 2009-04-30 18:18= :49 UTC (rev 869) +++ trunk/docs/reference/src/main/docbook/en-US/custom.dtd 2009-04-30 22:11= :02 UTC (rev 870) @@ -1,4 +1,4 @@ - + = @@ -50,7 +50,7 @@ = Logger"> ClassLoaderFactory"> -StandardClassLoaderFactory<= /ulink>"> +StandardClassLoaderFactory"> = = @@ -58,6 +58,7 @@ Graph.Batch"> <= interface>Subgraph"> Node"> +Workspace"> Results"> <= classname>Location"> ExecutionContext"> @@ -74,13 +75,16 @@ RepositoryConnectionFactory"> RepositorySourceListener"> RepositorySourceCapabilities<= /classname>"> -InMemoryRepository"> -InMemoryRepositorySource<= /classname>"> +InMemoryRepository"> +InMemoryRepositorySource<= /classname>"> CachePolicy"> -Request"> +Request"> CompositeRequest"> ReadNodeRequest"> CopyBranchRequest"> +InvalidRequestException"> +InvalidWorkspaceException"> +UnsupportedRequestException"> RequestProcessor"> StreamSequencer"> SequencerOutput"> Modified: trunk/docs/reference/src/main/docbook/en-US/master.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/docs/reference/src/main/docbook/en-US/master.xml 2009-04-30 18:18= :49 UTC (rev 869) +++ trunk/docs/reference/src/main/docbook/en-US/master.xml 2009-04-30 22:11= :02 UTC (rev 870) @@ -34,7 +34,7 @@ Reference Guide &versionNumber; &versionNumber; - 1 + 4 Modified: trunk/pom.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/pom.xml 2009-04-30 18:18:49 UTC (rev 869) +++ trunk/pom.xml 2009-04-30 22:11:02 UTC (rev 870) @@ -403,6 +403,11 @@ org.jboss.dna + dna-jcr-tck + ${pom.version} + + + org.jboss.dna dna-connector-federation ${pom.version} @@ -413,9 +418,59 @@ org.jboss.dna + dna-connector-store-jpa + ${pom.version} + + + org.jboss.dna + dna-connector-filesystem + ${pom.version} + + + org.jboss.dna + dna-connector-svn + ${pom.version} + + + org.jboss.dna dna-mimetype-detector-aperture ${pom.version} + + org.jboss.dna + dna-sequencer-cnd + ${pom.version} + + + org.jboss.dna + dna-sequencer-images + ${pom.version} + + + org.jboss.dna + dna-sequencer-java + ${pom.version} + + + org.jboss.dna + dna-sequencer-mp3 + ${pom.version} + + + org.jboss.dna + dna-sequencer-msoffice + ${pom.version} + + + org.jboss.dna + dna-sequencer-xml + ${pom.version} + + + org.jboss.dna + dna-sequencer-zip + ${pom.version} + --===============7796121288330436734==--