1. Chris Hyzer University of Pennsylvania
Grouper API part 1
Chris Hyzer University of Pennsylvania

2. Contents Overview of the Grouper API Versioning Download Databases
Grouper Loader
DDL
Quickstart data

3. Grouper components
as of v2.0
January 2012

4. Overview of the Grouper API
The Grouper registry is the database tables where the Grouper data lives
The Grouper API is
the grouper.jar (and dependent jars) and
config files that query and manipulate the Grouper registry
The Grouper API is a dependent component to the UI, WS, Grouper Loader (daemons), and LDAPPC-NG

5. Overview of the Grouper API (continued)
The Grouper API can run in multiple places for the same registry
The Grouper Java API (from grouper.jar) is also referred to as the Grouper API

6. Versioning Grouper API versioning is a three number system Example:
2 is the major version number
0 is the minor version
3 is the build number

7. Versioning (continued)
Only bug fixes and small impact enhancements will be put in next build number of a major/minor release
Generally a substantial release (new major or minor number) is done yearly

8. Versioning (continued)
All components of Grouper are released at the same time with the same version number
Note: the Provisioning Service Provider is not on the same release schedule as other Grouper components
If you are upgrading Grouper, it is generally a good idea to upgrade all Grouper components together
For each major/minor release, refer to the
Upgrade instructions
List of environment changes

9. Versioning for Web Services
Grouper WS are versioned
Each request sends the protocol version that is expected to be returned
Grouper WS are backwards compatible
Clients do not need to be upgraded when the server is

10. Download
Grouper packages of all official versions are hosted on the Grouper web server linked from:
If you download the Grouper Installer, it can download most other packages for you
Some Grouper packages are hosted on Maven's central repository

12. Databases
Grouper uses the open source Hibernate library for Java / SQL persistence
Generally Grouper supports all the databases that Hibernate supports, as long as it supports:
Transactions
Large indexes
Complex SQL queries

13. Databases (continued)
It is best if you use Oracle, MySQL, or Postgres
Grouper is also tested with SQL server, though its indexes can be problematic
It is unsupported to use another database except HQL in development

14. Grouper Loader
The Grouper Loader can keep groups in sync with SQL databases or LDAP
The Grouper Loader is compatible with any SQL database that you have a Java driver for (it does not have to be the Grouper registry database)
The Grouper Loader uses simple SQL and not hibernate
Generally it is a good idea to keep your Loader query in a database view

15. grouper.hibernate.properties config file

16. Database DDL DDL is Data Definition Language
This is the SQL that creates the database objects (tables, views, indexes, etc.) used by Grouper
DDL is not standard across database vendors
Hibernate does not give fine-grained control of DDL

17. Database DDL (continued)
Grouper uses Jakarta DDLUtils to generate DDL for each database vendor
You can run a GSH command to initialize or upgrade the DDL in your database
Grouper will analyze the database to upgrade it
Follow the Grouper upgrade instructions carefully

18. Database DDL (continued)
Grouper GSH can either:
Init/upgrade the registry for you -or-
Generate a script that you can review
The Grouper GSH DDL command can also run SQL to affect the data in the database on upgrades

19. Database DDL continued
C:\mchyzer\grouper\trunk\grouper\bin>gsh -registry -runscript

20. Database DDL (continued)
C:\mchyzer\grouper\trunk\grouper\bin>gsh -registry -check

21. Quickstart data There are quickstart users for a SQL datasource
There is an export of a quickstart project that you can import into your registry to have sample groups, etc.
The Grouper Installer or GSH can install the quickstart users and data for you
The quickstart users need to be resolvable before the quickstart data can be loaded

22. Quickstart data (continued)

23. Quickstart data (continued)
C:\mchyzer\grouper\trunk\grouper\bin>gsh -registry -runsqlfile subjects.sql

24. Quickstart data (continued)
C:\mchyzer\grouper\trunk\grouper\bin>gsh -registry -runsqlfile subjects.sql

25. Quickstart data (continued)
C:\mchyzer\grouper\trunk\grouper\bin>gsh -registry -runsqlfile subjects.sql

26. Quickstart data (continued)
C:\mchyzer\grouper\trunk\grouper\bin>gsh -registry -runsqlfile subjects.sql

27. Quiz
Click on the quiz link in the Youtube video description to reinforce your knowledge of this topic

28. Thanks!
Further information:
Infosheets, mail lists, wiki, downloads, etc:
Grouper demo server: