Sakai app and tool naming tips

Information

This contains information about the things you have to watch out for when choosing names for apps and tools in Sakai. Many names have to be unique and others must match with something in order for the tool to work correctly. Name collisions will tend to cause errors on Tomcat startup.

Naming conventions and tips

tool definition file (e.g. sakai.tasklist.xml) must declare a unique tool id

Sample tool id xml

<?xml version="1.0" encoding="UTF-8"?>
<registration>
	<tool id="sakai.tasklist"
		title="Programmer's Cafe - Task List"
		description="Programmer's Cafe - Task List">
		<category name="course" />
		<category name="project" />
	</tool> 
</registration>

Note: always use the unique name (tasklist) of your tool in the tool id (choose a longer name if it is shorter than 8 chars)

Maven xml files must define unique IDs

project.xml (maven 1 - sakai 2.4.x and earlier) defines an id (e.g. sakai-tasklist-tool) that must be unique

Sample project.xml

<?xml version="1.0" encoding="UTF-8"?>
<project>
	<pomVersion>3</pomVersion>
	<extend>../../master/project.xml</extend>
	<name>Programmer's Cafe - Task List</name>
	<groupId>sakaiproject</groupId>
	<id>sakai-tasklist-tool</id>
	<currentVersion>${sakai.version}</currentVersion>
...

pom.xml (maven 2 - sakai 2.5.x and later) defines an artifactId (e.g. tasklist-tool) that must be unique

Sample pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
   <modelVersion>4.0.0</modelVersion>
   <name>Programmer's Cafe - Task List</name>
   <groupId>org.sakaiproject.tasklist</groupId>
   <artifactId>tasklist-tool</artifactId>
...

Note: always use the unique name (tasklist) of your tool in every maven file

Spring beans declared in the component space (application context) must be unique
Sample components.xml
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN"
	"http://www.springframework.org/dtd/spring-beans.dtd">
<beans>
	<bean id="org.sakaiproject.crudplus.logic.CrudPlusLogic"
		class="org.sakaiproject.crudplus.logic.impl.CrudPlusLogicImpl"
		init-method="init">
</beans>
```
- Note: always use the fully qualified classpath in any beans you declare in your components.xml or applicationContext.xml (or other application context spring config files)
  - Good: edu.vt.sakai.evaluation.logic.EvaluationSettings, org.sakaiproject.crudplus.logic.CrudPlusLogic
  - Bad: mySettings, myLogic
Database table names have to be unique (not in use by any other deployed tool)
- Note: Include the name of your tool as a prefix for every table name
  - Good: EVAL_ANSWER, TASKLIST_TASK, MYTOOL_ITEM
  - Bad: ANSWER, ITEM, CONFIG
Hibernate HBM file names have to be unique (not in use be any other deployed tool)
- Note: Include the name of your tool as a prefix for every Hibernate file
  - Good: EvaluationAnswer.hbm.xml, TasklistTask.hbm.xml
  - Bad: Answer.hbm.xml, Task.hbm.xml
Hibernate persistent entity names have to be unique
- Note: Include the name of your tool as a prefix for every persistent class OR use the entity-name attribute on the class tag in the HBM file
  Example: <class name="org.sakaiproject.evaluation.model.Answer" table="EVAL_ANSWER" entity-name="EvalAnswer">
  - Good: EvalAnswer.java, TasklistTask.java
  - Bad: Answer.java, Task.java

web.xml (tool/src/webapp/WEB-INF) defined servlet name must match tool id

Sample web.xml

<servlet>
        <servlet-name>sakai.tasklist</servlet-name>
        <servlet-class>org.sakaiproject.tool.tasklist.TasklistTool</servlet-class>
        <load-on-startup>1</load-on-startup>
</servlet>

Note: always change the web.xml and tool xml files at the same time