<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE document PUBLIC "-//MAKUMBA//DTD Documentation V2.0//EN" "document-v20-mak.dtd">

<document>
	<header>
		<title>Information about the Business Logic in Makumba</title>
	</header>
	<body>
	<section id="Login">
		<title>Login</title>
		<p>Login is done as a result of a missing attribute (possibly invoked in <sub>checkAttributes</sub>), when a find<sub>{AttributeName}</sub>  method is called. The missing attribute is the principal that needs to log in. </p>
		<p>If the attribute cannot be found due to wrong login information, <sub>org.makumba.UnauthenticatedException</sub> is usually thrown.</p>
		<p>The principal (the person who logs in) can have more members (e.g. group, Lbg, Company representatives). E.g. the findCompany() method will check to see if the authentication (email_address and password) corresponds to any company representative of that company. If yes, it will return that company.</p>
		<p>Login can be done in 2 ways:</p>
		
		<ol>
		<li>(Http basic authentication login: will set the attributes $username, $password )</li>
		<li>cookie login: done in a page called login.jsp, in the same directory or (if missing) in any of the parents. It should contain at least: </li>
		</ol>
		
		<p>	|	&lt;mak:login&gt;<br/>
  			|	&lt;input type=text name=username&gt;<br/>
  			|	&lt;input type=password name=password&gt;<br/>
  			|	&lt;input type=submitgt;<br/>
			|	&lt;/mak:login&gt;
		</p>
		<p>	The login form will pass further (as hidden arguments) all the http parameters it got. 
			Note that &lt;mak:login&gt;  is only needed upon automatic login (a page displayed when the user requested another page, that needs authentication). 
			If you wish to ask for login manually in a startup page, a normal HTML form is enough.</p>
		<p>To cancel out a certain attribute, in order to produce a new login, the logout tag is available</p>
		<p>|   &lt;mak:logout actor="student"/&gt;</p>
		<p>You can remove (cancel-out, logout) multiple attributes from the session by using <sub>&lt;mak:logout actor="attribute name"&gt;</sub> several times and/or by using the star (*) wildcard, e.g.:</p>
		<p>
		 	|	&lt;mak:logout actor="demo_*"/&gt; (attributes whose names start with "demo_")<br/>
			|	&lt;mak:logout actor="*app"/&gt; (attributes whose names end with "app")<br/>
			|	&lt;mak:logout actor="*"/&gt; (all attributes; this "invalidates" the session)</p>
		<p>(Later on, logout request might be done in the business logic, with a method <sub>deleteAttributes(param)</sub>  that can accept either a String (with optional '*') or a String[]. ) </p>
		<p>(Later: to accomodate servers that don't do session tracking, login can be done by a query condition rather than by doing a query (once per session) to find an attribute. This way, it won't need to do a query (to check the authentication) at every access, but that condition will make sure that authentication is done. )</p>
		<p>
		<sub>(&lt;mak:object from="best.Student stud" where ="stud.$login()"&gt; ...&lt;/mak:object&gt; </sub><br/>
		then methodBestSudentLogin("stud") will return "stud.auth.email=$username AND stud.auth.password=$password" <br/>
		This can be used for http authentication with no session tracking. )</p>
		<p>(Later: if an attribute has multiple values, a choose<sub>{AttributeName}.jsp</sub> page is shown. For example, a super user (for that area) can choose to act as any student, Lbg, or company... A student member of more local Vivaldi teams can choose to act for any of the viv teams, etc. )</p>
		
	</section>

	</body>
</document>